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This manual describes the programming features of the UNIX system. It 
provides neither a general overview of the UNIX system nor details of the 
implementation of the system. 

Not all commands, features, and facilities described in this manual are 
available in every UNIX system. Some of the features require additional utili- 
ties which may not exist on your system. 

This manual is divided into five sections, some containing interfiled 
subclasses: 

1. Commands 

2. System Calls. 

3. Subroutines: 

3C. C Programming Language Libraries 
3S. Standard I/O Library Routines 
3M. Mathematical Library Routines 
3N. Networking Support Utilities 
3X. Specialized Libraries 
3F. FORTRAN Programming Libraries 

4. File Formats. 

5. Miscellaneous Facilities. 

Section 1 ( Commands ) describes commands that support C and other pro- 
gramming languages. 

Section 2 ( System Calls) describes the access to the services provided by 
the UNIX system kernel, including the C language interface. 

Section 3 ( Subroutines ) describes the available subroutines. Their binary 
versions reside in various system libraries in the directories /lib and /usr/lib. 
See intro ( 3) for descriptions of these libraries and the files in which they are 
stored. 

Section 4 (File Formats) documents the structure of particular kinds of 
files; for example, the format of the output of the link editor is given in 
a. out (A). Excluded are files used by only one command (for example, the 
assembler's intermediate files). In general, the C language structures 
corresponding to these formats can be found in the directories /usr/include 
and /usr/include/sys. 
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Section 5 ( Miscellaneous Facilities) contains a variety of things. Included 
are descriptions of character sets, macro packages, etc. 

References with numbers other than those above mean that the utility is 
contained in the appropriate section of another manual. References with (1) 
following the command mean that the utility is contained in this manual or 
the User's Reference Manual (P-H). Those followed by (1M), (7), or (8) are con- 
tained in the System Administrator's Reference Manual (AT&T). 

Each section consists of a number of independent entries of a page or so 
each. Entries within each section are alphabetized, with the exception of the 
introductory entry that begins each section (also Section 3 is in alphabetical 
order by suffixes). Some entries may describe several routines, commands, 
etc. In such cases, the entry appears only once, alphabetized under its "pri- 
mary" name, the name that appears at the upper corners of each manual 
page. 

All entries are based on a common format, not all of whose parts always 
appear: 

■ The NAME part gives the name(s) of the entry and briefly states its pur- 
pose. 

■ The SYNOPSIS part summarizes the use of the program being 
described. A few conventions are used, particularly in Section 2 
(System Calls): 

□ Boldface strings are literals and are to be typed just as they appear. 

□ Italic strings usually represent substitutable argument prototypes 
and program names found elsewhere in the manual. 

□ Square brackets [] around an argument prototype indicate that the 
argument is optional. When an argument prototype is given as 
'name' or 'file/ it always refers to a file name. 

□ Ellipses . . . are used to show that the previous argument prototype 
may be repeated. 

□ A final convention is used by the commands themselves. An argu- 
ment beginning with a minus — , plus +, or equal sign = is often 
taken to be some sort of flag argument, even if it appears in a posi- 
tion where a file name could appear. Therefore, it is unwise to 
have files whose names begin with — , +, or =. 
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■ The DESCRIPTION part describes the utility. 

■ The EXAMPLE(S) part gives example(s) of usage, where appropriate. 

■ The FILES part gives the file names that are built into the program. 

■ The SEE ALSO part gives pointers to related information. 

■ The DIAGNOSTICS part discusses the diagnostic indications that may 
be produced. Messages that are intended to be self-explanatory are not 
listed. 

■ The NOTES part gives generally "helpful hints" about the use of the 
utility. 

■ The WARNINGS part points out potential pitfalls. 

■ The BUGS part gives known bugs and sometimes deficiencies. 

■ The CAVEATS part gives details of the implementation that might 
affect usage. 

A "Table of Contents" and a "Permuted Index" derived from that table pre- 
cedes section 1. 

Some of the manual pages refer to the MAU, which is the WE®32106 
Math Acceleration Unit. This unit is a high performance floating point sup- 
port processor chip that supports a large subset of IEEE (Institute of Electrical 
and Electronics Engineers) P754 Draft 10 requirements for Binary Floating 
Point Arithmetic. 
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NAME 

intro — introduction to programming commands 
DESCRIPTION 

This section describes, in alphabetical order, commands available for the AT&T 
3B2 Computer. The top of each page indicates the utilities package to which the 
command belongs. The packages are: 

Advanced C Utilities 
AT&T Windowing Utilities 
C Programming Language Utilities 
Directory and File Management Utilities 
Extended Software Generation System Utilities 
Software Generation System Utilitites 
Source Code Control System Utilities 
Terminal Information Utilities 

COMMAND SYNTAX 

Unless otherwise noted, the commands described accept options and other argu- 
ments according to the following syntax: 

name [option(s)] [cmdarg(s)] 
where: 

name is the name of an executable file 

option is — no argletter (s) or 

— argletter < > optarg 

where: 

noargletter is a single letter representing an option without an 
option-argument 

argletter is a single letter representing an option requiring an 
option-argument 

< > is optional white space 

optarg is an option-argument (character string) satisfying the 
preceding argletter. 

cmdarg is a path name (or other command argument) not beginning with 

or " by itself indicating the standard input. 

Throughout the manual pages there are references to TMPDIR, BINDIR, INCDIR, 
LIBDIR, and LLIBD1R. These represent directory names whose value is specified 
on each manual page as necessary. For example, TMPDIR might refer to /tmp 
or /usr/tmp. These are not environment variables and cannot be set. [There is 
also an environment variable called TMPDIR which can be set. See 
tmpnam( 3S).] 
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SEE ALSO 

exit(2), wait(2), getopt(3C). 

getopts(l) in the User's Reference Manual , 

DIAGNOSTICS 

Upon termination, each command returns two bytes of status, one supplied by 
the system and giving the cause for termination, and (in the case of "normal" 
termination) one supplied by the program [see wait( 2) and exit (2)]. The former 
byte is 0 for normal termination; the latter is customarily 0 for successful execu- 
tion and non-zero to indicate troubles such as erroneous parameters, or bad or 
inaccessible data. It is called variously "exit code", "exit status", or "return 
code", and is described only where special conventions are involved. 

WARNINGS 

Some commands produce unexpected results when processing files containing 
null characters. These commands often treat text input lines as strings and 
therefore become confused upon encountering a null character (the string termi- 
nator) within a line. 
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NAME 

admin — create and administer SCCS files 
SYNOPSIS 

admin [-n] [-i[name]] [-rrel] [-t[name]] [-fflag[flag-val]] [-dflag[flag-val]] 
[— alogin] [— elogin] [— m[mrlist]] [— y[comment]] [— h] [— z] files 

DESCRIPTION 

admin is used to create new SCCS files and change parameters of existing ones. 
Arguments to admin, which may appear in any order, consist of keyletter argu- 
ments, which begin with — , and named files (note that SCCS file names must 
begin with the characters s.). If a named file does not exist, it is created, and its 
parameters are initialized according to the specified keyletter arguments. Param- 
eters not initialized by a keyletter argument are assigned a default value. If a 
named file does exist, parameters corresponding to specified keyletter arguments 
are changed, and other parameters are left as is. 

If a directory is named, admin behaves as though each file in the directory were 
specified as a named file, except that non-SCCS files (last component of the path 
name does not begin with s.) and unreadable files are silently ignored. If a 
name of — is given, the standard input is read; each line of the standard input is 
taken to be the name of an SCCS file to be processed. Again, non-SCCS files and 
unreadable files are silently ignored. 

The keyletter arguments are as follows. Each is explained as though only one 
named file is to be processed since the effects of the arguments apply indepen- 
dently to each named file. 

— n This keyletter indicates that a new SCCS file is to be 

created. 

— i [name] The name of a file from which the text for a new SCCS file 

is to be taken. The text constitutes the first delta of the 
file (see — r keyletter for delta numbering scheme). If the i 
keyletter is used, but the file name is omitted, the text is 
obtained by reading the standard input until an end-of-file 
is encountered. If this keyletter is omitted, then the SCCS 
file is created empty. Only one SCCS file may be created 
by an admin command on which the i keyletter is sup- 
plied. Using a single admin to create two or more SCCS 
files requires that they be created empty (no — i keyletter). 
Note that the — i keyletter implies the — n keyletter. 

— rrel The release into which the initial delta is inserted. This 

keyletter may be used only if the — i keyletter is also used. 
If the — r keyletter is not used, the initial delta is inserted 
into release 1. The level of the initial delta is always 1 (by 
default initial deltas are named 1.1). 

— t [name] The name of a file from which descriptive text for the 

SCCS file is to be taken. If the — t keyletter is used and 
admin is creating a new SCCS file (the — n and/or — i 
keyletters also used), the descriptive text file name must 
also be supplied. In the case of existing SCCS files: (1) a 
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b 

cceil 



ffloor 



dSID 

i[str] 



j 



1 list 



< list > 



n 



— t keyletter without a file name causes removal of 
descriptive text (if any) currently in the SCCS file, and (2) a 
— t keyletter with a file name causes text (if any) in the 
named file to replace the descriptive text (if any) currently 
in the SCCS file. 

This keyletter specifies a flag, and, possibly, a value for the 
flag, to be placed in the SCCS file. Several f keyletters 
may be supplied on a single admin command line. The 
allowable flags and their values are: 

Allows use of the — b keyletter on a get( 1) command to 
create branch deltas. 

The highest release (i.e., "ceiling"), a number greater than 
0 but less than or equal to 9999, which may be retrieved 
by a get( 1) command for editing. The default value for an 
unspecified c flag is 9999. 

The lowest release (i.e., "floor"), a number greater than 0 
but less than 9999, which may be retrieved by a get( 1) 
command for editing. The default value for an unspecified 
f flag is 1. 

The default delta number (SIDs+1) to be used by a get( 1) 
command. 

Causes the "No id keywords (ge6 )” message issued by 
get( 1) or delta( 1) to be treated as a fatal error. In the 
absence of this flag, the message is only a warning. The 
message is issued if no SCCS identification keywords [see 
get( 1)] are found in the text retrieved or stored in the SCCS 
file. If a value is supplied, the keywords must exactly 
match the given string, however the string must contain a 
keyword, and no embedded newlines. 

Allows concurrent get( 1) commands for editing on the 
same SIDs+1 of an SCCS file. This allows multiple concurrent 
updates to the same version of the SCCS file. 

A list of releases to which deltas can no longer be made 
(get — e against one of these "locked" releases fails). The 
list has the following syntax: 

::= <range> 1 < list > , <range> 

< range >~::= I a 

The character a in the list is equivalent to specifying all 
releases for the named SCCS file. 

Causes delta( 1) to create a "null" delta in each of those 
releases (if any) being skipped when a delta is made in a 
new release (e.g., in making delta 5,1 after delta 2.7, 
releases 3 and 4 are skipped). These null deltas serve as 
"anchor points" so that branch deltas may later be created 
from them. The absence of this flag causes skipped 
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Hist 

—alogin 



—elogin 



releases to be non-existent in the SCCS file, preventing 
branch deltas from being created from them in the future. 

User definable text substituted for all occurrences of the 
%Q% keyword in SCCS file text retrieved by get( 1). 

Module name of the SCCS file substituted for all 
occurrences of the %M% keyword in SCCS file text 
retrieved by get(l). If the m flag is not specified, the value 
assigned is the name of the SCCS file with the leading s. 
removed. 

Type of module in the SCCS file substituted for all 
occurrences of %Y% keyword in SCCS file text retrieved 
by get(l). 

Causes delta( 1) to prompt for Modification Request (MR) 
numbers as the reason for creating a delta. The optional 
value specifies the name of an MR number validity 
checking program [see delta( 1)]. (If this flag is set when 
creating an SCCS file, the m keyletter must also be used 
even if its value is null). 

Causes removal (deletion) of the specified flag from an 
SCCS file. The — d keyletter may be specified only when 
processing existing SCCS files. Several — d keyletters may 
be supplied on a single admin command. See the — f 
keyletter for allowable flag names. 

A list of releases to be "unlocked". See the — f keyletter 
for a description of the 1 flag and the syntax of a list. 

A login name, or numerical UNIX system group ID, to be 
added to the list of users which may make deltas 
(changes) to the SCCS file. A group ID is equivalent to 
specifying all login names common to that group ID. 
Several a keyletters may be used on a single admin com- 
mand line. As many logins, or numerical group IDs, as 
desired may be on the list simultaneously. If the list of 
users is empty, then anyone may add deltas. If login or 
group ID is preceded by a ! they are to be denied permis- 
sion to make deltas. 

A login name, or numerical group ID, to be erased from 
the list of users allowed to make deltas (changes) to the 
SCCS file. Specifying a group ID is equivalent to speci- 
fying all login names common to that group ID. Several e 
keyletters may be used on a single admin command line. 
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— m [mrlist] The list of Modification Requests (MR) numbers is inserted 

into the SCCS file as the reason for creating the initial 
delta in a manner identical to delta( 1). The v flag must be 
set and the MR numbers are validated if the v flag has a 
value (the name of an MR number validation program). 
Diagnostics will occur if the v flag is not set or MR valida- 
tion fails. 



— y [comment] The comment text is inserted into the SCCS file as a com- 

ment for the initial delta in a manner identical to that of 
delta( 1). Omission of the — y keyletter results in a default 
comment line being inserted in the form: 

date and time created YY/MM/DD HH:MM:SS by login 

The — y keyletter is valid only if the — i and/or — n 
keyletters are specified (i.e., a new SCCS file is being 
created). 

-h Causes admin to check the structure of the SCCS file [see 

sccsfile(5)], and to compare a newly computed check-sum 
(the sum of all the characters in the SCCS file except those 
in the first line) with the check-sum that is stored in the 
first line of the SCCS file. Appropriate error diagnostics 
are produced, keyletter inhibits writing on the file, so that 
it nullifies the effect of any other keyletters supplied, and 
is, therefore, only meaningful when processing existing 
files. 

— z The SCCS file check-sum is recomputed and stored in the 

first line of the SCCS file (see -h, above). 

Note that use of this keyletter on a truly corrupted file 
may prevent future detection of the corruption. 

The last component of all SCCS file names must be of the form s .file-name. 
New SCCS files are given mode 444 [see chmod( 1)]. Write permission in 
the pertinent directory is, of course, required to create a file. All writing 
done by admin is to a temporary x-file, called x.file-name, [see get( 1)], 
created with mode 444 if the admin command is creating a new SCCS file, 
or with the same mode as the SCCS file if it exists. After successful execu- 
tion of admin, the SCCS file is removed (if it exists), and the x-file is 
renamed with the name of the SCCS file. This ensures that changes are 
made to the SCCS file only if no errors occurred. 

It is recommended that directories containing SCCS files be mode 755 and 
that SCCS files themselves be mode 444. The mode of the directories 
allows only the owner to modify SCCS files contained in the directories. 
The mode of the SCCS files prevents any modification at all except by SCCS 
commands. 



If it should be necessary to patch an SCCS file for any reason, the mode 
may be changed to 644 by the owner allowing use of ed( 1). Care must be 
taken! The edited file should always be processed by an admin — h to check 
for corruption followed by an admin — z to generate a proper check-sum. 



6 




ADMIN(l) 



(Source Code Control System Utilities) 



ADMIN(l) 



Another admin — h is recommended to ensure the SCCS file is valid. 

admin also makes use of a transient lock file (called z.file-name), which is 
used to prevent simultaneous updates to the SCCS file by different users. 
See get( 1) for further information. 

FILES 

g-file Existed before the execution of delta ; removed after completion 

of delta. 

p-file Existed before the execution of delta; may exist after completion 

of delta. 

q-file Created during the execution of delta; removed after completion 

of delta. 

x-file Created during the execution of delta; renamed to SCCS file 

after completion of delta. 

z-file Created during the execution of delta; removed during the exe- 

cution of delta. 

d-file Created during the execution of delta; removed after completion 

of delta. 

/usr/bin/bdiff Program to compute differences between the "gotten" file and 
the g-file. 

SEE ALSO 

delta(l), get(l), prs(l), what(l), sccsfile(4). 

ed(l), help(l) in the User's Reference Manual. 

DIAGNOSTICS 

Use help( 1) for explanations. 
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NAME 

ar — archive and library maintainer for portable archives 
SYNOPSIS 

ar key [posname] afile [name] ... 

DESCRIPTION 

The ar command maintains groups of files combined into a single archive file. 
Its main use is to create and update library files as used by the link editor. It 
can be used, though, for any similar purpose. The magic string and the file 
headers used by ar consist of printable ASCII characters. If an archive is com- 
posed of printable files, the entire archive is printable. 

When ar creates an archive, it creates headers in a format that is portable across 
all machines. The portable archive format and structure is described in detail in 
ar( 4). The archive symbol table [described in ar(4)] is used by the link editor 
[ld( 1)] to effect multiple passes over libraries of object files in an efficient 
manner. An archive symbol table is only created and maintained by ar when 
there is at least one object file in the archive. The archive symbol table is in a 
specially named file which is always the first file in the archive. This file is 
never mentioned or accessible to the user. Whenever the ar( 1) command is used 
to create or update the contents of such an archive, the symbol table is rebuilt. 
The s option described below will force the symbol table to be rebuilt. 

Unlike command options, the command key is a required part of ar ' s command 
line. The key (which may begin with a — ) is formed with one of the following 
letters: drqtpmx. Arguments to the key, alternatively, are made with one or 
more of the following set: vuaibcls. Posname is an archive member name used 
as a reference point in positioning other files in the archive. Afile is the archive 
file. The names are constituent files in the archive file. The meanings of the key 
characters are as follows: 

d Delete the named files from the archive file. 

r Replace the named files in the archive file. If the optional character u is 

used with r, then only those files with dates of modification later than 
the archive files are replaced. If an optional positioning character from 
the set abi is used, then the posname argument must be present and 
specifies that new files are to be placed after (a) or before (b or I) 
posname. Otherwise new files are placed at the end. 

q Quickly append the named files to the end of the archive file. Optional 
positioning characters are invalid. The command does not check 
whether the added members are already in the archive. This option is 
useful to avoid quadratic behavior when creating a large archive piece- 
by-piece. Unchecked, the file may grow exponentially up to the second 
degree. 

t Print a table of contents of the archive file. If no names are given, all 

files in the archive are tabled. If names are given, only those files are 
tabled. 

p Print the named files in the archive. 
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m Move the named files to the end of the archive. If a positioning char- 
acter is present, then the posname argument must be present and, as in r, 
specifies where the files are to be moved. 

x Extract the named files. If no names are given, all files in the archive 
are extracted. In neither case does x alter the archive file. 

meanings of the key arguments are as follows: 

Give a verbose file-by-file description of the making of a new archive 
file from the old archive and the constituent files. When used with t, 
give a long listing of all information about the files. When used with x, 
precede each file with a name. 

Suppress the message that is produced by default when afile is created. 

Place temporary files in the local (current working) directory rather than 
in the default temporary directory, TMPDIR. 

Force the regeneration of the archive symbol table even if ar( 1) is not 
invoked with a command which will modify the archive contents. This 
command is useful to restore the archive symbol table after the strip( 1) 
command has been used on the archive. 

FILES 

$TMPDIR/* temporary files 

$TMPDIR is usually /usr/tmp but can be redefined by setting the environment 
variable TMPDIR [see tempnamQ in tmpnam( 3S)]. 

SEE ALSO 

ld(l), lorder(l), strip(l), tmpnam(3S), a.out(4), ar(4) 

NOTES 

If the same file is mentioned twice in an argument list, it may be put in the 
archive twice. 
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NAME 

as — common assembler 
SYNOPSIS 

as [options] filename 
DESCRIPTION 

The as command assembles the named file. The following flags may be 
specified in any order: 

— o objfile Put the output of the assembly in objfile. By default, the output file 

name is formed by removing the .s suffix, if there is one, from the 

input file name and appending a .o suffix. 

— n Turn off long/short address optimization. By default, address optimi- 

zation takes place. 

— m Run the m4 macro processor on the input to the assembler. 

— R Remove (unlink) the input file after assembly is completed. 

— dl Do not produce line number information in the object file. 

—V Write the version number of the assembler being run on the standard 

error output. 

-Y [md],dir 

Find the m4 preprocessor (m) and/or the file of predefined macros (d) 
in directory dir instead of in the customary place. 

FILES 

TMPDIR/* temporary files 

TMPDIR is usually /usr/tmp but can be redefined by setting the environment 
variable TMPDIR [see tempnamQ in tmpnam( 3S)]. 

SEE ALSO 

cc(l), ld(l), m4(l), nm(l), strip(l), tmpnam(3S), a.out(4) 

WARNING 

If the — m (m4 macro processor invocation) option is used, keywords for m4 [see 
m4(l)] cannot be used as symbols (variables, functions, labels) in the input file 
since m4 cannot determine which are assembler symbols and which are real m4 
macros. 

BUGS 

The .align assembler directive may not work in the .text section when optimiza- 
tion is performed. 

CAVEATS 

Arithmetic expressions may only have one forward referenced symbol per 
expression. 

NOTES 

Wherever possible, the assembler should be accessed through a compilation 
system interface program [such as cc( 1)]. 
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NAME 

cb — C program beautifier 
SYNOPSIS 

cb [ -s ] [ -j ] [ -1 leng ] [ file ... ] 

DESCRIPTION 

The cb comand reads C programs either from its arguments or from the standard 
input, and writes them on the standard output with spacing and indentation that 
display the structure of the code. Under default options, cb preserves all user 
new-lines. 

cb accepts the following options. 

— s Canonicalizes the code to the style of Kernighan and Ritchie in The 

C Programming Language. 

— j Causes split lines to be put back together. 

—1 leng Causes cb to split lines that are longer than leng. 

SEE ALSO 

cc(l). 

The C Programming Language. Prentice-Hall, 1978. 

BUGS 

Punctuation that is hidden in preprocessor statements will cause indentation 
errors. 
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NAME 

cc — C compiler 

SYNOPSIS 

cc [ options ] files 

DESCRIPTION 

The cc command is the interface to the C Compilation System. The compilation 
tools consist of a preprocessor, compiler, optimizer, assembler and link editor. 
The cc command processes the supplied options and then executes the various 
tools with the proper arguments. The cc command accepts several types of files 
as arguments: 

Files whose names end with .c are taken to be C source programs and may be 
preprocessed, compiled, optimized, assembled and link edited. The compilation 
process may be stopped after the completion of any pass if the appropriate 
options are supplied. If the compilation process runs through the assembler 
then an object program is produced and is left in the file whose name is that of 
the source with .o substituted for .c. However, the .o file is normally deleted if a 
single C program is compiled and then immediately link edited. In the same 
way, files whose names end in .s are taken to be assembly source programs, and 
may be assembled and link edited; and files whose names end in .i are taken to 
be preprocessed C source programs and may be compiled, optimized, assembled 
and link edited. Files whose names do not end in .c, .s or .i are handed to the 
link editor. 

Since the cc command usually creates files in the current directory during the 
compilation process, it is necessary to run the cc command in a directory in 
which a file can be created. 

The following options are interpreted by cc: . 

— c Suppress the link editing phase of the compilation, and do not remove 

any produced object files. 

— ds Don't generate symbol attribute information for the symbolic debugger. 

— dl Don't generate symbolic debugging line number information. This and 

the above flag may be used in conjunction as — dsl (— dsl is the default 
unless the — g flag is given). 

— f Cause the link editor to load floating point emulation code. This option 

is needed only when loading old objects which use floating point. 
Current objects do not require floating point emulation code. 

— g Cause the compiler to generate additional information needed for the 
use of sdb (1). 

— o outfile 

Produce an output object file by the name outfile. The name of the 
default file is a.out. This is a link editor option. 

— p Arrange for the compiler to produce code that counts the number of 
times each routine is called; also, if link editing takes place, profiled ver- 
sions of libc.a and libm.a (with — lm option) are linked and monitor^ 3C) 
is automatically called. A mon.out file will then be produced at normal 
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termination of execution of the object program. An execution profile can 
then be generated by use of prof( 1). 

— qp Arrange for profiled code to be produced where the p argument pro- 
duces identical results to the — p option [allows profiling with prof( 1)]. 

— B string 

-tjTp02alJ 

These options will be removed in the next release. Use the — Y option. 

— E Run only cpp( 1) on the named C programs, and send the result to the 

standard output. 

— F Cause the compiler to generate code for single precision arithmetic 

whenever an expression contains float variables and no doubles. 

— H Print out on stderr the pathname of each file included during the current 

compilation. 

— O Do compilation phase optimization. This option will not have any affect 

on .s files. 

— P Run only cpp( 1) on the named C programs and leave the result in 

corresponding files suffixed .i. This option is passed to cpp( 1). 

— S Compile and do not assemble the named C programs, and leave the 

assembler-language output in corresponding files suffixed .s. 

— V Print the version of the compiler, optimizer, assembler and/or link 

editor that is invoked. 

— Wc,argl[,arg2...] 

Hand off the arguments] argi to pass c where c is one of [p02al] indi- 
cating the preprocessor, compiler, optimizer, assembler, or link editor, 
respectively. For example: -Wa,-m passes — m to the assembler. 

-Y [p02alSILU ], dirname 

Specify a new pathname, dirname, for the locations of the tools and 
directories designated in the first argument. [p02alSILU] represents: 

p preprocessor 

0 compiler 
2 optimizer 
a assembler 

1 link editor 

S directory containing the start-up routines 
I default include directory searched by cpp( 1) 

L first default library directory searched by ld( 1) 

U second default library directory searched by ld( 1) 

If the location of a tool is being specified, then the new pathname for 
the tool will be dirname /tool. If more than one — Y option is applied to 
any one tool or directory, then the last occurrence holds. 

The cc command also recognizes — C, — D, — H, —I and — U and passes these 
options and their arguments directly to the preprocessor without using the — W 
option. Similarly, the cc command recognizes —a, —1, — m, — o, — r, — s, — t, — u, 
— x, — z, — L, — M and — V and passes these options and their arguments directly 
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to the loader. See the manual pages for cpp( 1) and ld( 1) for descriptions. 

Other arguments are taken to be C compatible object programs, typically pro- 
duced by an earlier cc run, or perhaps libraries of C compatible routines and are 
passed directly to the link editor. These programs, together with the results of 
any compilations specified, are link edited (in the order given) to produce an 
executable program with name a.out unless the — o option of the link editor is 
used. 

If the cc command is put in a file prefix cc the prefix will be parsed off the com- 
mand and used to call the tools, i.e., prefix tool. For example, OLDcc will call 
OLDcpp, OLDcomp, OLDoptim, OLDas, and OLDld and will link OLDcrtl.o. 
Therefore, one MUST be careful when moving the cc command around. The 
prefix will apply to the preprocessor, compiler, optimizer, assembler, link editor, 
and the start-up routines. 

The C language standard was extended to allow arbitrary length variable names. 
The option pair "— Wp,— T —WO,— XT" will cause cc to truncate arbitrary length 
variable names. 

FILES 

file.c 
file.i 
file.o 
file.s 
a.out 

LIBDIR /*crtl.o 
LIBDIR/ crtn.o 
TMPD1R/* 

LIBDIR/ cpp 
LIBDIR/ comp 
LIBDIR/ optim 
BINDIR/ as 
BINDIR/ Id 
LIBDIR/ libc.a 
L/BDIR/libc_s.a 

LIBDIR is usually /lib 
BINDIR is usually /bin 

TMPDIR is usually /usr/tmp but can be redefined by setting the environment 
variable TMPDIR [see tempnamQ in tmpnam( 3S)]. 

SEE ALSO 

as(l), ld(l), cpp(l), gencc(l), lint(l), prof(l), sdb(l), tmpnam(3S). 

Kernighan, B. W., and Ritchie, D. M., The C Programming Language , Prentice- 
Hall, 1978. 

DIAGNOSTICS 

The diagnostics produced by the C compiler are sometimes cryptic. Occasional 
messages may be produced by the assembler or link editor. If an outdated ver- 
sion of the assembler has been installed over the assembler that is part of Issue 
4 of the C Programming Language Utilities and that outdated assembler is used 
with the Issue 4 compiler, one of the following error messages will appear. 



C source file 

preprocessed C source file 
object file 

assembly language file 
link edited output 
start-up routine 
start-up routine 
temporary files 
preprocessor, cpp( 1) 
compiler 
optimizer 
assembler, as( 1) 
link editor, ld( 1) 
standard C library 
standard C shared library 
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aline 2 : invalid instruction name 
... ".version" 

aline 2 : Invalid instruction name 
aline 2 : syntax error 

To ensure that the compilation system works correctly, re-install the C Program- 
ming Language Utilities Issue 4 assembler. 

NOTES 

By default, the return value from a compiled C program is completely random. 
The only two guaranteed ways to return a specific value is to explicitly call 
exit( 2) or to leave the function mainQ with a "return expression construct. 
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NAME 

cdc — change the delta commentary of an SCCS delta 
SYNOPSIS 

cdc — rSID [— m[mrlist]] [— y[comment]] files 
DESCRIPTION 

cdc changes the delta commentary, for the SID (SCCS IDentification string) 
specified by the — r keyletter, of each named SCCS file. 

Delta commentary is defined to be the Modification Request (MR) and comment 
information normally specified via the delta( 1) command (— m and — y 
keyletters). 

If a directory is named, cdc behaves as though each file in the directory were 
specified as a named file, except that non-SCCS files (last component of the path 
name does not begin with s.) and unreadable files are silently ignored. If a 
name of — is given, the standard input is read (see WARNINGS) and each line of 
the standard input is taken to be the name of an SCCS file to be processed. 

Arguments to cdc, which may appear in any order, consist of keyletter argu- 
ments and file names. 



All the described keyletter arguments apply independently to each named file: 

—rSID Used to specify the S CCS IDentification (SID) string of a 

delta for which the delta commentary is to be changed. 



—mmrlist 



If the SCCS file has the v flag set [see admin( 1)] then a list 
of MR numbers to be added and/or deleted in the delta 
commentary of the SID specified by the — r keyletter may 
be supplied. A null MR list has no effect. 



MR entries are added to the list of MRs in the same 
manner as that of delta( 1). In order to delete an MR, pre- 
cede the MR number with the character ! (see EXAMPLES). 
If the MR to be deleted is currently in the list of MRs, it is 
removed and changed into a "comment" line. A list of all 
deleted MRs is placed in the comment section of the delta 



commentary and preceded uy a conunent line stating tnat 
they were deleted. 



If — m is not used and the standard input is a terminal, the 
prompt MRs? is issued on the standard output before the 
standard input is read; if the standard input is not a ter- 
minal, no prompt is issued. The MRs? prompt always pre- 
cedes the comments? prompt (see — y keyletter). 



MRs in a list are separated by blanks and/or tab charac- 
ters. An unescaped new-line character terminates the MR 
list. 



Note that if the v flag has a value [see admin( 1)], it is 
taken to be the name of a program (or shell procedure) 
which validates the correctness of the MR numbers. If a 
non-zero exit status is returned from the MR number 
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validation program, cdc terminates and the delta commen- 
tary remains unchanged. 

— y [comment] Arbitrary text used to replace the comment (s) already 

existing for the delta specified by the — r keyletter. The 
previous comments are kept and preceded by a comment 
line stating that they were changed. A null comment has 
no effect. 

If -y is not specified and the standard input is a terminal, 
the prompt comments? is issued on the standard output 
before the standard input is read; if the standard input is 
not a terminal, no prompt is issued. An unescaped new- 
line character terminates the comment text. 

Simply stated, the keyletter arguments are either (1) if you made the delta, you 
can change its delta commentary; or (2) if you own the file and directory you 
can modify the delta commentary. 

EXAMPLES 

cdc — rl.6 — m"bl78-12345 !bl77-54321 bl79-00001" -ytrouble s.file 

adds bl78- 12345 and bl79-00001 to the MR list, removes bl77-54321 from the 
MR list, and adds the comment trouble to delta 1.6 of s.file. 

cdc —rl.6 s.file 

MRs? !bl77-54321 bl78-12345 bl79-00001 
comments? trouble 

does the same thing. 

WARNINGS 

If SCCS file names are supplied to the cdc command via the standard input (— 
on the command line), then the — m and — y keyletters must also be used. 

FILES 

x-file [see delta( 1)] 

z-file [see delta{ 1)] 

SEE ALSO 

admin(l), delta(l), get(l), prs(l), sccsfile(4). 
help(l) in the User's Reference Manual. 

DIAGNOSTICS 

Use help( 1) for explanations. 
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NAME 

cflow — generate C flowgraph 
SYNOPSIS 

cflow [-r] [-ix] [— i_ ] [-dnum] files 
DESCRIPTION 

The cflow command analyzes a collection of C, yacc, lex, assembler, and object 
files and attempts to build a graph charting the external references. Files 
suffixed with .y, .1, and .c are yacced, lexed, and C-preprocessed as appropriate. 
The results of the preprocessed files, and files suffixed with .i, are then run 
through the first pass of lint( 1). Files suffixed with .s are assembled. Assembled 
files, and files suffixed with .o, have information extracted from their symbol 
tables. The results are collected and turned into a graph of external references 
which is displayed upon the standard output. 

Each line of output begins with a reference number, followed by a suitable 
number of tabs indicating the level, then the name of the global symbol fol- 
lowed by a colon and its definition. Normally only function names that do not 
begin with an underscore are listed (see the — i options below). For information 
extracted from C source, the definition consists of an abstract type declaration 
(e.g., char *), and, delimited by angle brackets, the name of the source file and 
the line number where the definition was found. Definitions extracted from 
object files indicate the file name and location counter under which the symbol 
appeared (e.g., text). Leading underscores in C-style external names are deleted. 

Once a definition of a name has been printed, subsequent references to that 
name contain only the reference number of the line where the definition may be 
found. For undefined references, only < > is printed. 

As an example, given the following in file.c: 
int i; 
main() 

f(); 

g(); 

f(); 

} 

f() 

{ 

i = h(); 
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the command 

cflow — ix file.c 
produces the output 

1 main: int(), < file.c 4> 

2 f: int(), < file.c 11 > 

3 h: <> 

4 i: int, < file.c 1> 

5 g: <> 

When the nesting level becomes too deep, the output of cflow can be piped to 
pr( 1), using the — e option, to compress the tab expansion to something less than 
every eight spaces. 

In addition to the — D, —I, and — U options [which are interpreted just as they 
are by cc(l) and cpp( 1)], the following options are interpreted by cflow : 

— r Reverse the "caller:callee" relationship producing an inverted listing 

showing the callers of each function. The listing is also sorted in lexi- 
cographical order by callee. 

— ix Include external and static data symbols. The default is to include only 

functions in the flowgraph. 

— i Include names that begin with an underscore. The default is to exclude 

these functions (and data if —ix is used). 

— dnum The num decimal integer indicates the depth at which the flowgraph is 
cut off. By default this is a very large number. Attempts to set the 
cutoff depth to a nonpositive integer will be ignored. 

DIAGNOSTICS 

Complains about bad options. Complains about multiple definitions and only 
believes the first. Other messages may come from the various programs used 
(e.g., the C-preprocessor). 

SEE ALSO 

as(l), cc(l), cpp(l), lex(l), lint(l), nm(l), yacc(l). 
pr(l) in the User's Reference Manual 

BUGS 

Files produced by lex( 1) and yacc( 1) cause the reordering of line number declara- 
tions which can confuse cflow. To get proper results, feed cflow the yacc or lex 
input. 
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NAME 

comb — combine SCCS deltas 

SYNOPSIS 

comb files 

DESCRIPTION 

comb generates a shell procedure [see sh( 1)] which, when run, will reconstruct 
the given SCCS files. The reconstructed files will, hopefully, be smaller than the 
original files. The arguments may be specified in any order, but all keyletter 
arguments apply to all named SCCS files. If a directory is named, comb behaves 
as though each file in the directory were specified as a named file, except that 
non-SCCS files (last component of the path name does not begin with s.) and 
unreadable files are silently ignored. If a name of — is given, the standard input 
is read; each line of the input is taken to be the name of an SCCS file to be pro- 
cessed; non-SCCS files and unreadable files are silently ignored. The generated 
shell procedure is written on the standard output. 

The keyletter arguments are as follows. Each is explained as though only one 
named file is to be processed, but the effects of any keyletter argument apply 
independently to each named file, each get — e generated, this argument causes 
the reconstructed file to be accessed at the release of the delta to be created, oth- 
erwise the reconstructed file would be accessed at the most recent ancestor. Use 
of the — o keyletter may decrease the size of the reconstructed SCCS file. It may 
also alter the shape of the delta tree of the original file, argument causes comb 
to generate a shell procedure which, when run, will produce a report giving, for 
each file: the file name, size (in blocks) after combining, original size (also in 
blocks), and percentage change computed by: 

100 * (original — combined) / original 

It is recommended that before any SCCS files are actually combined, one should 
use this option to determine exactly how much space is saved by the combining 
process. SCCS ID entification string (SID) of the oldest delta to be preserved. All 
older deltas are discarded in the reconstructed file, list (see get( 1) for the syntax 
of a list) of deltas to be preserved. All other deltas are discarded. 

If no keyletter arguments are specified, comb will preserve only leaf deltas and 
the minimal number of ancestors needed to preserve the tree. 

FILES 

s.COMB The name of the reconstructed SCCS file, 

comb????? Temporary. 

SEE ALSO 

admin(l), delta(l), get(l), prs(l), sccsfile(4). 
help(l), sh(l) in the User's Reference Manual 

DIAGNOSTICS 

Use help( 1) for explanations. 
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BUGS 

comb may rearrange the shape of the tree of deltas. It may not save any space; 
in fact, it is possible for the reconstructed file to actually be larger than the ori- 
ginal. 
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NAME 

conv — common object file converter 
SYNOPSIS 

conv [-a] [-o] [-p] -t target [- | files] 

DESCRIPTION 

The conv command converts object files in the common object file format from 
their current byte ordering to the byte ordering of the target machine. The con- 
verted file is written to file.v. The conv command can be used on either the 
source (sending) or target (receiving) machine. 

Command line options are: 

— indicates that the names of files should be read from the standard 

input. 

—a If the input file is an archive, produce the output file in the UNIX 

System V Release 2.0 portable archive format. 

— o If the input file is an archive, produce the output file in the old 

(pre- UNIX System V) archive format. 

— p If the input file is an archive, produce the output file in the UNIX 

System V Release 1.0 random access archive format. 

— t target Convert the object file to the byte ordering of the machine ( target ) 

to which the object file is being shipped. This may be another host 
or a target machine. Legal values for target are: pdp, vax, ibm, x86, 
bl6, n3b, mc68 and m32. 

The conv command is meant to ease the problems created by a multi-host cross- 
compilation development environment. The conv command is best used within a 
procedure for shipping object files from one machine to another. 

The conv command will recognize and produce archive files in three formats: the 
pre- UNIX System V format, the UNIX System V Release 1.0 random access 
format, and the UNIX System V Release 2.0 portable ASCII format. By default, 
conv will create the output archive file in the same format as the input file. To 
produce an output file in a different format than the input file, use the — a, o, 
or — p option. If the output archive format is the same as the input format, the 
archive symbol table will be converted, otherwise the symbol table will be 
stripped from the archive. The ar( 1) command with its — t and — s options must 
be used on the target machine to recreate the archive symbol table. 

EXAMPLE 

To ship object files from a VAX to a 3B2 Computer, execute the following com- 
mands: 

conv — t m32 *.out 
uucp *.out.v my3b2!~/rje/ 
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DIAGNOSTICS 

The diagnostics are self-explanatory. Fatal diagnostics on the command lines 
cause termination. Fatal diagnostics on an input file cause the program to con- 
tinue to the next input file. 

CAVEATS 

The conv command will not convert archives from one format to another if both 
the source and target machines have the same byte ordering. The UNIX system 
tool convert ( 1) should be used for this purpose. 

SEE ALSO 

ar(l), convert(l), ar(4), a.out(4). 
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NAME 

convert — convert archive files to common formats 
SYNOPSIS 

convert infile outfile 
DESCRIPTION 

The convert command transforms input in file to output outfile. Infile must be a 
UNIX System V Release 1.0 archive file and outfile will be the equivalent UNIX 
System V Release 2.0 archive file. All other types of input to the convert com- 
mand will be passed unmodified from the input file to the output file (along 
with appropriate warning messages). 

Infile must be different from outfile. 

FILES 

TMPDIR/ conv* temporary files 

TMPDIR is usually /usr/tmp but can be redefined by setting the environment 
variable TMPDIR [see tempnami) in tmpnam( 3S)]. 

SEE ALSO 

ar(l), tmpnam(3S), a.out(4), ar(4) 
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NAME 

cpp — the C language preprocessor 
SYNOPSIS 

LIBDIR/cpp [ option ... ] [ ifile [ ofile ] ] 



DESCRIPTION 

The C language preprocessor, cpp, is invoked as the first pass of any C compila- 
tion by the cc(l) command. Thus cpp's output is designed to be in a form 
acceptable as input to the next pass of the C compiler. As the C language 
evolves, cpp and the rest of the C compilation package will be modified to 
follow these changes. Therefore, the use of cpp other than through the cc(l) 
command is not suggested, since the functionality of cpp may someday be 
moved elsewhere. See m4( 1) for a general macro processor. 

cpp optionally accepts two file names as arguments. Ifile and ofile are respec- 
tively the input and output for the preprocessor. They default to standard input 
and standard output if not supplied. 

The following options to cpp are recognized: 

— P Preprocess the input without producing the line control information used 

by the next pass of the C compiler. 

— C By default, cpp strips C-style comments. If the — C option is specified, 

all comments (except those found on cpp directive lines) are passed 
along. 



-U name 

Remove any initial definition of name, where name is a reserved symbol 
that is predefined by the particular preprocessor. Following is the 
current list of these possibly reserved symbols. On AT&T 3B2 and 3B5 
Computers, unix and one of u3b2 or u3b5 are defined, 
operating system: unix, dmert, geos, ibm, os, tss 

hardware: interdata, pdpll, u370, u3b, u3b5, u3b2, 

u3b20d, vax 



UNIX system variant: RES, RT 

lint( 1): lint 



-D name 

—Dname=def 

Define name with value def as if by a #define. If no =def is given, name 
is defined with value 1. The — D option has lower precedence than the 
— U option. That is, if the same name is used in both a — U option and a 
— D option, the name will be undefined regardless of the order of the 
options. 

— T The — T option forces cpp to use only the first eight characters to distin- 

guish preprocessor symbols and is included for backward compatibility. 

—I dir Change the algorithm for searching for #include files whose names do 

not begin with / to look in dir before looking in the directories on the 
standard list. Thus, #include files whose names are enclosed in "" will 
be searched for first in the directory of the file with the #include line. 
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then in directories named in —I options, and last in directories on a stan- 
dard list. For #include files whose names are enclosed in <>, the 
directory of the file with the #include line is not searched. 

— Y dir Use directory dir in place of the standard list of directories when 
searching for #include files. 

— H Print, one per line on standard error, the path names of included files. 

Two special names are understood by cpp. The name LINE is defined as the 

current line number (as a decimal integer) as known by cpp, and FILE is 

defined as the current file name (as a C string) as known by cpp. They can be 
used anywhere (including in macros) just as any other defined name. 

All cpp directive lines start with # in column 1 . Any number of blanks and tabs 
is allowed between the # and the directive. The directives are: 

#define name token-string 

Replace subsequent instances of name with token-string. 

#define name( arg, arg ) token-string 

Notice that there can be no space between name and the (. Replace sub- 
sequent instances of name followed by a (, a list of comma-separated sets 
of tokens, and a ) followed by token-string, where each occurrence of an 
arg in the token-string is replaced by the corresponding set of tokens in 
the comma-separated list. When a macro with arguments is expanded, 
the arguments are placed into the expanded token-string unchanged. 
After the entire token-string has been expanded, cpp re-starts its scan for 
names to expand at the beginning of the newly created token-string. 

#undef name 

Cause the definition of name (if any) to be forgotten from now on. No 
additional tokens are permitted on the directive line after name. 

#ident " string " 

Put string into the .comment section of an object file. 

#include " filename " 

#include < filename > 

Include at this point the contents of filename (which will then be run 
through cpp). When the <filename> notation is used, filename is only 
searched for in the standard places. See the —I and — Y options above 
for more detail. No additional tokens are permitted on the directive line 
after the final "or > . 

#line integer-constant " filename " 

Causes cpp to generate line control information for the next pass of the 
C compiler. Integer-constant is the line number of the next line and 
filename is the file from which it comes. If " filename " is not given, the 
current file name is unchanged. No additional tokens are permitted on 
the directive line after the optional filename. 

#endif 

Ends a section of lines begun by a test directive (#if, #ifdef, or 
#ifndef). Each test directive must have a matching #endif. No addi- 
tional tokens are permitted on the directive line. 
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#ifdef name 

The lines following will appear in the output if and only if name has 
been the subject of a previous #define without being the subject of an 
intervening #undef. No additional tokens are permitted on the directive 
line after name . 

#ifndef name 

The lines following will appear in the output if and only if name has not 
been the subject of a previous # define. No additional tokens are per- 
mitted on the directive line after name . 

#if constant-expression 

Lines following will appear in the output if and only if the constant- 
expression evaluates to non-zero. All binary non-assignment C opera- 
tors, the ?: operator, the unary — , !, and ~ operators are all legal in 
constant-expression. The precedence of the operators is the same as 
defined by the C language. There is also a unary operator defined, 
which can be used in constant-expression in these two forms: defined ( 
name ) or defined name. This allows the utility of #ifdef and #ifndef 
in a #if directive. Only these operators, integer constants, and names 
which are known by cpp should be used in constant-expression. In par- 
ticular, the sizeof operator is not available. 

To test whether either of two symbols, foo and fum, are defined, use 

#if defined(foo) | defined(fum) 

#elif constant-expression 

An arbitrary number of #elif directives is allowed between a #if, 
#ifdef, or #ifndef directive and a #else or #endif directive. The lines 
following the #elif directive will appear in the output if and only if the 
preceding test directive evaluates to zero, all intervening #elif directives 
evaluate to zero, and the constant-expression evaluates to non-zero. If 
constant-expression evaluates to non-zero, all succeeding #elif and #else 
directives will be ignored. Any constant-expression allowed in a #if 
directive is allowed in a #elif directive. 

#else The lines following will appear in the output if and only if the preceding 
test directive evaluates to zero, and all intervening #elif directives 
evaluate to zero. No additional tokens are permitted on the directive 
line. 

The test directives and the possible #else directives can be nested. 

FILES 

INCDIR standard directory list for #include files, usually 

/usr /include 

LIBDIR usually /lib 

SEE ALSO 

cc(l), lint(l), m4(l). 
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DIAGNOSTICS 

The error messages produced by cpp are intended to be self-explanatory. The 
line number and file name where the error occurred are printed along with the 
diagnostic. 

NOTES 

The unsupported — W option enables the #class directive. If it encounters a 
# class directive, cpp will exit with code 27 after finishing all other processing. 
This option provides support for "C with classes". 

Because the standard directory for included files may be different in different 
environments, this form of #include directive: 

#include <file.h> 

should be used, rather than one with an absolute path, like: 

#include " /usr/include/f ile . h" 
cpp warns about the use of the absolute pathname. 
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NAME 

cprs — compress a common object file 

SYNOPSIS 

cprs [-p] filel file2 

DESCRIPTION 

The cprs command reduces the size of a common object file, filel, by removing 
duplicate structure and union descriptors. The reduced file, filel , is produced as 
output. 

The sole option to cprs is: 

— p Print statistical messages including: total number of tags, total duplicate 

tags, and total reduction of filel . 

SEE ALSO 

strip(l), a.out(4), syms(4). 
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NAME 

ctrace — C program debugger 
SYNOPSIS 

ctrace [options] [file] 

DESCRIPTION 

The ctrace command allows you to follow the execution of a C program, 
statement-by-statement. The effect is similar to executing a shell procedure with 
the —x option, ctrace reads the C program in file (or from standard input if you 
do not specify file), inserts statements to print the text of each executable state- 
ment and the values of all variables referenced or modified, and writes the 
modified program to the standard output. You must put the output of ctrace 
into a temporary file because the cc( 1) command does not allow the use of a 
pipe. You then compile and execute this file. 

As each statement in the program executes it will be listed at the terminal, fol- 
lowed by the name and value of any variables referenced or modified in the 
statement, followed by any output from the statement. Loops in the trace 
output are detected and tracing is stopped until the loop is exited or a different 
sequence of statements within the loop is executed. A warning message is 
printed every 1000 times through the loop to help you detect infinite loops. The 
trace output goes to the standard output so you can put it into a file for exami- 
nation with an editor or the bfs( 1) or tail(\) commands. 

The options commonly used are: 

— f functions Trace only these functions. 

—v functions Trace all but these functions. 

You may want to add to the default formats for printing variables. Long and 
pointer variables are always printed as signed integers. Pointers to character 
arrays are also printed as strings if appropriate. Char, short, and int variables 
are also printed as signed integers and, if appropriate, as characters. Double 
variables are printed as floating point numbers in scientific notation. You can 
request that variables be printed in additional formats, if appropriate, with these 
options: 

—o Octal 

—x Hexadecimal 

— u Unsigned 

— e Floating point 

These options are used only in special circumstances: 

—1 n Check n consecutively executed statements for looping trace output, 
instead of the default of 20. Use 0 to get all the trace output from loops. 
— s Suppress redundant trace output from simple assignment statements and 

string copy function calls. This option can hide a bug caused by use of 

the — operator in place of the == operator. 

— t n Trace n variables per statement instead of the default of 10 (the max- 
imum number is 20). The Diagnostics section explains when to use this 
option. 

— P Run the C preprocessor on the input before tracing it. You can also use 
the — D, —I, and — U cpp( 1) options. 
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These options are used to tailor the run-time trace package when the traced pro- 
gram will run in a non-UNIX System environment: 

— b Use only basic functions in the trace code, that is, those in ctype (3C), 
printf( 3S), and string( 3C). These are usually available even in cross- 
compilers for microprocessors. In particular, this option is needed when 
the traced program runs under an operating system that does not have 
signal(2), jflush( 3S), longjmp( 3C), or setjmp( 3C). 

-p string 

Change the trace print function from the default of 'printf('. For 
example, 'fprintf(stderr/ would send the trace to the standard error 
output. 

— r / Use file / in place of the runtime.c trace function package. This lets you 
change the entire print function, instead of just the name and leading 
arguments (see the — p option). 

EXAMPLE 

If the file Ic.c contains this C program: 

1 #include <stdio.h> 

2 main() /* count lines in input * / 

3 { 

4 int c, nl; 

5 

6 nl = 0; 

7 while ((c = getchar()) != EOF) 

8 if (c = VO 

9 ++nl; 

10 printf("%d\n", nl); 

11 } 

and you enter these commands and test data: 
cc lc.c 
a. out 
1 

(cntl-d) 

the program will be compiled and executed. The output of the program will be 
the number 2, which is not correct because there is only one line in the test data. 
The error in this program is common, but subtle. If you invoke ctrace with these 
commands: 

ctrace lc.c >temp.c 

cc temp.c 

a.out 

the output will be: 

2 main() 

6 nl - 0; 

/* n i === 0 */ 

7 while ((c = getcharQ) !— EOF) 

The program is now waiting for input. If you enter the same test data as before, 
the output will be: 

/* c == 49 or T */ 
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8 if (c = V) 

/* c == 10 or '\n' */ 

9 ++nl; 

/* nl == 1 */ 

7 while ((c = getcharQ) != EOF) 

/* c == 10 or '\n' */ 

8 if (c = V) 

/* c == 10 or '\n' */ 

9 ++nl; 

/* nl == 2 */ 

7 while ((c = getchar()) != EOF) 

If you now enter an end of file character (cntl-d) the final output will be: 

/* c == -1 */ 

10 printf("%d\n", nl); 

/* nl — 2 */2 
return 

Note that the program output printed at the end of the trace line for the nl vari- 
able. Also note the return comment added by ctrace at the end of the trace 
output. This shows the implicit return at the terminating brace in the function. 

The trace output shows that variable c is assigned the value 'T in line 7, but in 
line 8 it has the value '\n'. Once your attention is drawn to this if statement, 
you will probably realize that you used the assignment operator (=) in place of 
the equality operator (==). You can easily miss this error during code reading. 

EXECUTION-TIME TRACE CONTROL 

The default operation for ctrace is to trace the entire program file, unless you use 
the — f or — v options to trace specific functions. This does not give you 
statement-by-statement control of the tracing, nor does it let you turn the tracing 
off and on when executing the traced program. 

You can do both of these by adding ctroffQ and ctronQ function calls to your 
program to turn the tracing off and on, respectively, at execution time. Thus, 
you can code arbitrarily complex criteria for trace control with if statements, and 
you can even conditionally include this code because ctrace defines the 
CTRACE preprocessor variable. For example: 

#ifdef CTRACE 

if (c == T && i > 1000) 
ctron(); 

#endif 

You can also call these functions from sdb( 1) if you compile with the — g option. 
For example, to trace all but lines 7 to 10 in the main function, enter: 

sdb a. out 
main: 7b ctroff() 
main: lib ctron() 
r 

You can also turn the trace off and on by setting static variable tr_ct_ to 0 and 1, 
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respectively. This is useful if you are using a debugger that cannot call these 
functions directly. 

DIAGNOSTICS 

This section contains diagnostic messages from both ctrace and cc( 1), since the 
traced code often gets some cc warning messages. You can get cc error mes- 
sages in some rare cases, all of which can be avoided. 

ctrace Diagnostics 

warning: some variables are not traced in this statement 

Only 10 variables are traced in a statement to prevent the C compiler 
"out of tree space; simplify expression" error. Use the — t option to 
increase this number. 

warning: statement too long to trace 

This statement is over 400 characters long. Make sure that you are 
using tabs to indent your code, not spaces. 

cannot handle preprocessor code , use — P option 

This is usually caused by #ifdef/#endif preprocessor statements in the 
middle of a C statement, or by a semicolon at the end of a #define 
preprocessor statement. 

'if ... else if sequence too long 

Split the sequence by removing an else from the middle. 

possible syntax error , try —P option 

Use the — P option to preprocess the ctrace input, along with any 
appropriate — D, —I, and — U preprocessor options. If you still get the 
error message, check the Warnings section below. 

Cc Diagnostics 

warning: illegal combination of pointer and integer 
warning: statement not reached 
warning: sizeof returns 0 

Ignore these messages. 

compiler takes size of function 

See the ctrace "possible syntax error" message above. 

yacc stack overflow 

See the ctrace "'if ... else if' sequence too long" message above. 
out of tree space; simplify expression 

Use the — t option to reduce the number of traced variables per state- 
ment from the default of 10. Ignore the "ctrace: too many variables to 
trace" warnings you will now get. 

redeclaration of signal 

Either correct this declaration of signal{ 2), or remove it and #include 
<signal.h>. 

SEE ALSO 

signal(2), ctype(3C), fclose(3S), printf(3S), setjmp(3C), string(3C). 
bfs(l), tail(l) in the User's Reference Manual . 
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WARNINGS 

You will get a ctrace syntax error if you omit the semicolon at the end of the last 
element declaration in a structure or union, just before the right brace (}). This 
is optional in some C compilers. 

Defining a function with the same name as a system function may cause a 
syntax error if the number of arguments is changed. Just use a different name. 

ctrace assumes that BADMAG is a preprocessor macro, and that EOF and NULL 
are #defined constants. Declaring any of these to be variables, e.g., "int EOF;", 
will cause a syntax error. 

BUGS 

ctrace does not know about the components of aggregates like structures, unions, 
and arrays. It cannot choose a format to print all the components of an aggre- 
gate when an assignment is made to the entire aggregate, ctrace may choose to 
print the address of an aggregate or use the wrong format (e.g., 3.149050e-311 
for a structure with two integer members) when printing the value of an aggre- 
gate. 

Pointer values are always treated as pointers to character strings. 

The loop trace output elimination is done separately for each file of a multi-file 
program. This can result in functions called from a loop still being traced, or the 
elimination of trace output from one function in a file until another in the same 
file is called. 

FILES 

/usr/lib/ctrace/runtime.c run-time trace package 
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NAME 

cxref — generate C program cross-reference 
SYNOPSIS 

cxref [ options ] files 
DESCRIPTION 

The cxref command analyzes a collection of C files and attempts to build a 
cross-reference table, cxref uses a special version of cpp to include #define'd 
information in its symbol table. It produces a listing on standard output of all 
symbols (auto, static, and global) in each file separately, or, with the — c option, 
in combination. Each symbol contains an asterisk (*) before the declaring refer- 
ence. 

In addition to the — D, —I and — U options [which are interpreted just as they are 
by cc(l) and cpp( 1)], the following options are interpreted by cxref : 

—c Print a combined cross-reference of all input files. 

— w <num> 

Width option which formats output no wider than <num> (decimal) 
columns. This option will default to 80 if <num> is not specified or is 
less than 51. 

— o file Direct output to file. 

— s Operate silently; do not print input file names. 

—t Format listing for 80 -column width. 

FILES 

LLIBDIR usually /usr/lib 

LLlBDIR/x cpp special version of the C preprocessor. 

SEE ALSO 

cc(l), cpp(l). 

DIAGNOSTICS 

Error messages are unusually cryptic, but usually mean that you cannot compile 
these files. 

BUGS 

cxref considers a formal argument in a ttdefine macro definition to be a declara- 
tion of that symbol. For example, a program that # includes ctype.h, will contain 
many declarations of the variable c. 
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NAME 

delta — make a delta (change) to an SCCS file 
SYNOPSIS 

delta [ — rSID] [— s] [— n] [ — glist] [— m[mrlist]] [— y[comment]] [— p] files 



DESCRIPTION 

delta is used to permanently introduce into the named SCCS file changes that 
were made to the file retrieved by get( 1) (called the g-file, or generated file). 

delta makes a delta to each named SCCS file. If a directory is named, delta 
behaves as though each file in the directory were specified as a named file, 
except that non-SCCS files (last component of the path name does not begin 
with s.) and unreadable files are silently ignored. If a name of — is given, the 
standard input is read (see WARNINGS); each line of the standard input is taken 
to be the name of an SCCS file to be processed. 

delta may issue prompts on the standard output depending upon certain 
keyletters specified and flags [see admin( 1)] that may be present in the SCCS file 
(see — m and — y keyletters below). 



Keyletter arguments apply independently to each named file. 



—rSID 



—s 



— n 

-g list 



—m[mrlist] 



Uniquely identifies which delta is to be made to the SCCS 
file. The use of this keyletter is necessary only if two or 
more outstanding gets for editing (get — e) on the same 
SCCS file were done by the same person (login name). 
The SID value specified with the — r keyletter can be either 
the SID specified on the get command line or the SID to be 
made as reported by the get command [see get( 1)]. A 
diagnostic results if the specified SID is ambiguous, or, if 
necessary and omitted on the command line. 

Suppresses the issue, on the standard output, of the 
created delta's SID, as well as the number of lines inserted, 
deleted and unchanged in the SCCS file. 

Specifies retention of the edited g-file (normally removed 
at completion of delta processing). 

a list (see get( 1) for the definition of list) of deltas which 
are to be ignored when the file is accessed at the change 
level (SID) created by this delta. 

If the SCCS file has the v flag set [see admin( 1)] then a 
Modification Request (MR) number must be supplied as 
the reason for creating the new delta. 

If — m is not used and the standard input is a terminal, the 
prompt MRs? is issued on the standard output before the 
standard input is read; if the standard input is not a ter- 
minal, no prompt is issued. The MRs? prompt always pre- 
cedes the comments? prompt (see — y keyletter). 
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MRs in a list are separated by blanks and/or tab charac- 
ters. An unescaped new-line character terminates the MR 
list. 

Note that if the v flag has a value [see admin( 1)], it is 
taken to be the name of a program (or shell procedure) 
which will validate the correctness of the MR numbers. If 
a non-zero exit status is returned from the MR number 
validation program, delta terminates. (It is assumed that 
the MR numbers were not all valid.) 

— y [comment] Arbitrary text used to describe the reason for making the 

delta. A null string is considered a valid comment. 

If — y is not specified and the standard input is a terminal, 
the prompt comments? is issued on the standard output 
before the standard input is read; if the standard input is 
not a terminal, no prompt is issued. An unescaped new- 
line character terminates the comment text. 

Causes delta to print (on the standard output) the SCCS 
file differences before and after the delta is applied in a 
diff( 1) format. 

Existed before the execution of delta; removed after completion 
of delta . 

Existed before the execution of delta; may exist after completion 
of delta. 

Created during the execution of delta; removed after completion 
of delta. 

Created during the execution of delta; renamed to SCCS file 
after completion of delta. 

Created during the execution of delta; removed during the exe- 
cution of delta. 

Created during the execution of delta; removed after completion 
of delta. 

Program to compute differences between the "gotten" file and 
the g-file. 

WARNINGS 

Lines beginning with an SOH ASCII character (binary 001) cannot be placed in 
the SCCS file unless the SOH is escaped. This character has special meaning to 
SCCS [see sccsfile(4:) (5)] and will cause an error. 

A get of many SCCS files, followed by a delta of those files, should be avoided 
when the get generates a large amount of data. Instead, multiple get /delta 
sequences should be used. 

If the standard input (— ) is specified on the delta command line, the — m (if 
necessary) and — y keyletters must also be present. Omission of these keyletters 
causes an error to occur. 

Comments are limited to text strings of at most 512 characters. 



FILES 

g-file 

p-file 

q-file 

x-file 

z-file 

d-file 

/usr/bin/bdiff 
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SEE ALSO 

admin(l), cdc(l), get(l), prs(l), rmdel(l), sccsfile(4). 
bdiff(l), help(l) in the User's Reference Manual. 

DIAGNOSTICS 

Use help( 1) for explanations. 



DELTA(l) 
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NAME 

dis — object code disassembler 
SYNOPSIS 

dis [— o] [—V] [— L] [— s] [— d sec] [—da sec ] [— F function ] [— t sec] [—1 string] 

file ... 

DESCRIPTION 

The dis command produces an assembly language listing of file, which may be 
an object file or an archive of object files. The listing includes assembly state- 
ments and an octal or hexadecimal representation of the binary that produced 
those statements. 



The following options are interpreted by the disassembler and may be specified 
in any order. 

— o Print numbers in octal. The default is hexadecimal. 



-V 

-L 



-d sec 
-da sec 



Print, on standard error, the version number of the disassembler 
being executed. 

Lookup source labels in the symbol table for subsequent printing. 
This option works only if the file was compiled with additional 
debugging information [e.g., the — g option of cc(l)]. 

Perform symbolic disassembly- i.e., specify source symbol names 
for operands where possible. Symbolic disassembly output will 
appear on the line following the instruction. For maximal symbolic 
disassembly to be performed, the file must be compiled with addi- 
tional debugging information [e.g., the — g option of cc(l)]. Symbol 
names will be printed using C syntax. 

Disassemble the named section as data, printing the offset of the 
data from the beginning of the section. 

Disassemble the named section as data, printing the actual address 
of the data. 



— F function Disassemble only the named function in each object file specified 
on the command line. The — F option may be specified multiple 
times on the command line. 



— t sec Disassemble the named section as text. 

— 1 string Disassemble the library file specified by string. For example, one 

would issue the command dis — 1 x — 1 z to disassemble libx.a and 
libz.a. All libraries are assumed to be in LIBDIR. 



If the — d, —da or — t options are specified, only those named sections from each 
user-supplied file name will be disassembled. Otherwise, all sections containing 
text will be disassembled. 



On output, a number enclosed in brackets at the beginning of a line, such as [5], 
represents that the break-pointable line number starts with the following instruc- 
tion. These line numbers will be printed only if the file was compiled with addi- 
tional debugging information [e.g., the — g option of cc(l)]. An expression such 
as <40> in the operand field or in the symbolic disassembly, following a rela- 
tive displacement for control transfer instructions, is the computed address 
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within the section to which control will be transferred. A function name will 
appear in the first column, followed by (). 

FILES 

LIBDIR usually /lib. 

SEE ALSO 

as(l), cc(l), ld(l), a.out(4). 

DIAGNOSTICS 

The self-explanatory diagnostics indicate errors in the command line or problems 
encountered with the specified files. 
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NAME 

dump — dump selected parts of an object file 
SYNOPSIS 



dump [ options ] files 


DESCRIPTION 




The dump command dumps selected parts of each of its object file arguments. 

This command will accept both object files and archives of object files. It 
processes each file argument according to one or more of the following options: 


—a 


Dump the archive header of each member of each archive file argu- 
ment. 


“g 


Dump the global symbols in the symbol table of an archive. 


-f 


Dump each file header. 


-o 


Dump each optional header. 


-h 


Dump section headers. 


— s 


Dump section contents. 


— r 


Dump relocation information. 


-1 


Dump line number information. 


-t 


Dump symbol table entries. 


— z name 


Dump line number entries for the named function. 


— c 


Dump the string table. 


-L 


Interpret and print the contents of the .lib sections. 


The following modifiers are used in conjunction with the options listed above to 
modify their capabilities. 


— d number 


Dump the section number, number, or the range of sections starting 
at number and ending at the number specified by H-d. 


+d number 


Dump sections in the range either beginning with first section or 
beginning with section specified by — d. 


— n name 


Dump information pertaining only to the named entity. This 
modifier applies to — h, — s, —x, —1, and — t. 


-P 


Suppress printing of the headers. 


— t index 


Dump only the indexed symbol table entry. The — t used in con- 
junction with +t, specifies a range of symbol table entries. 


4-t index 


Dump the symbol table entries in the range ending with the 
indexed entry. The range begins at the first symbol table entry or 
at the entry specified by the — t option. 


— u 


Underline the name of the file for emphasis. 
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—v Dump information in symbolic representation rather than numeric 

(e.g., C STATIC instead of 0X02). This modifier can be used with all 
the above options except — s and — o options of dump. 

— z name,number 

Dump line number entry or range of line numbers starting at 
number for the named function. 

+z number Dump line numbers starting at either function name or number 
specified by — z, up to number specified by +z. 

Blanks separating an option and its modifier are optional. The comma separating 
the name from the number modifying the — z option may be replaced by a 
blank. 

The dump command attempts to format the information it dumps in a mean- 
ingful way, printing certain information in character, hex, octal or decimal 
representation as appropriate. 

SEE ALSO 

a.out(4), ar(4). 
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NAME 

gencc — create a front-end to the cc command 

SYNOPSIS 

gencc 

DESCRIPTION 

The gencc command is an interactive command designed to aid in the creation of 
a front-end to the cc command. Since hard-coded pathnames have been elim- 
inated from the C Compilation System (CCS), it is possible to move pieces of 
the CCS to new locations without recompiling the CCS. The new locations of 
moved pieces can be specified through the — Y option to the cc command. How- 
ever, it is inconvenient to supply the proper — Y options with every invocation of 
the cc command. Further, if a system administrator moves pieces of the CCS, 
such movement should be invisible to users. 

The front-end to the cc command which gencc generates is a one-line shell script 
which calls the cc command with the proper — Y options specified. The front- 
end to the cc command will also pass all user supplied options to the cc com- 
mand. 

gencc prompts for the location of each tool and directory which can be 
respecified by a — Y option to the cc command. If no location is specified, it 
assumes that that piece of the CCS has not been relocated. After all the loca- 
tions have been prompted for, gencc will create the front-end to the cc com- 
mand. 

gencc creates the front-end to the cc command in the current working directory 
and gives the file the same name as the cc command. Thus, gencc can not be 
run in the same directory containing the actual cc command. Further, if a system 
administrator has redistributed the CCS, the actual cc command should be 
placed somewhere which is not typically in a user's PATH (e.g., /lib). This will 
prevent users from accidentally invoking the cc command without using the 
front-end. 

CAVEATS 

gencc does not produce any warnings if a tool or directory does not exist at the 
specified location. Also, gencc does not actually move any files to new locations. 

FILES 

./cc front-end to cc 

SEE ALSO 

cc(l). 
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NAME 

get — get a version of an SCCS file 
SYNOPSIS 

get [— rSID] [— ccutoff] [— ilist] [— xlist] [— wstring] [— aseq-no.] [-k] [— e] [— l[p] 
hP] hm] hn] h»] hb] [~g] ht] file ... 

DESCRIPTION 

get generates an ASCII text file from each named SCCS file according to the 
specifications given by its keyletter arguments, which begin with — . The argu- 
ments may be specified in any order, but all keyletter arguments apply to all 
named SCCS files. If a directory is named, get behaves as though each file in the 
directory were specified as a named file, except that non-SCCS files (last com- 
ponent of the path name does not begin with s.) and unreadable files are silently 
ignored. If a name of — is given, the standard input is read; each line of the 
standard input is taken to be the name of an SCCS file to be processed. Again, 
non-SCCS files and unreadable files are silently ignored. 

The generated text is normally written into a file called the g-file whose name is 
derived from the SCCS file name by simply removing the leading s.; (see also 
FILES, below). 

Each of the keyletter arguments is explained below as though only one SCCS file 
is to be processed, but the effects of any keyletter argument applies indepen- 
dently to each named file. 

— r SID The SCCS ID entification string (SID) of the version (delta) of an 

SCCS file to be retrieved. Table 1 (pg. 47) shows, for the most 
useful cases, what version of an SCCS file is retrieved (as well as 
the SID of the version to be eventually created by delta ( 1) if the 
— e keyletter is also used), as a function of the SID specified. 

-c cutoff Cutoff date-time, in the form: 

YY[MM[DD[HH[MM[SS]]]]] 

No changes (deltas) to the SCCS file which were created after 
the specified cutoff date-time are included in the generated ASCII 
text file. Units omitted from the date-time default to their max- 
imum possible, values; that is, — c7502 is equivalent to 
— C750228235959. Any number of non-numeric characters may 
separate the various 2-digit pieces of the cutoff date-time. This 
feature allows one to specify a cutoff date in the form: 
C77/2/2 9:22:25". Note that this implies that one may use the 
%E% and %U% identification keywords (see below) for nested 
gets within, say the input to a send (1C) command: 

~!get c%E% %U%" s.file 

— i list A list of deltas to be included (forced to be applied) in the crea- 

tion of the generated file. The list has the following syntax: 

<list> ::= < range > I <list> , < range > 

< range > ::= SID I SID - SID 
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—xlist 
— e 



-b 



-k 

-1[P] 



“P 



— s 



SID, the SCCS Identification of a delta, may be in any form 
shown in the "SID Specified" column of Table 1. 

A list of deltas to be excluded in the creation of the generated 
file. See the — i keyletter for the list format. 

Indicates that the get is for the purpose of editing or making a 
change (delta) to the SCCS file via a subsequent use of delta( 1). 
The -e keyletter used in a get for a particular version (SID) of 
the SCCS file prevents further gets for editing on the same SID 
until delta is executed or the j (joint edit) flag is set in the SCCS 
file [see admin( 1)]. Concurrent use of get — e for different SIDs 
is always allowed. 

If the g-file generated by get with an — e keyletter is accidentally 
ruined in the process of editing it, it may be regenerated by re- 
executing the get command with the — k keyletter in place of 
the — e keyletter. 

SCCS file protection specified via the ceiling, floor, and author- 
ized user list stored in the SCCS file [see admin ( 1)] are enforced 
when the — e keyletter is used. 

Used with the — e keyletter to indicate that the new delta should 
have an SID in a new branch as shown in Table 1. This 
keyletter is ignored if the b flag is not present in the file [see 
admin( 1)] or if the retrieved delta is not a leaf delta. (A leaf 
delta is one that has no successors on the SCCS file tree.) 

Note: A branch delta may always be created from a non-leaf 
delta. Partial SIDs are interpreted as shown in the "SID 
Retrieved" column of Table 1. 

Suppresses replacement of identification keywords (see below) 
in the retrieved text by their value. The — k keyletter is implied 
by the — e keyletter. 

Causes a delta summary to be written into an l- file. If — lp is 
used then an l- file is not created; the delta summary is written 
on the standard output instead. See FILES for the format of the 
l- file. 

Causes the text retrieved from the SCCS file to be written on the 
standard output. No g-file is created. All output which nor- 
mally goes to the standard output goes to file descriptor 2 
instead, unless the — s keyletter is used, in which case it disap- 
pears. 

Suppresses all output normally written on the standard output. 
However, fatal error messages (which always go to file 
descriptor 2) remain unaffected. 
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— m Causes each text line retrieved from the SCCS file to be pre- 

ceded by the SID of the delta that inserted the text line in the 
SCCS file. The format is: SID, followed by a horizontal tab, fol- 
lowed by the text line. 

— n Causes each generated text line to be preceded with the %M% 

identification keyword value (see below). The format is: %M% 
value, followed by a horizontal tab, followed by the text line. 
When both the — m and — n keyletters are used, the format is: 
%M% value, followed by a horizontal tab, followed by the — m 
keyletter generated format. 

— g Suppresses the actual retrieval of text from the SCCS file. It is 

primarily used to generate an l-file, or to verify the existence of 
a particular SID. 

— t Used to access the most recently created delta in a given release 

(e.g., — rl), or release and level (e.g., — rl.2). 

— w string Substitute string for all occurrences of %W% when getting the 
file. 

—a seq-no. The delta sequence number of the SCCS file delta (version) to be 
retrieved [see sccsfile(5)]. This keyletter is used by the comb( 1) 
command; it is not a generally useful keyletter. If both the — r 
and —a keyletters are specified, only the —a keyletter is used. 
Care should be taken when using the —a keyletter in conjunc- 
tion with the — e keyletter, as the SID of the delta to be created 
may not be what one expects. The — r keyletter can be used 
with the —a and -e keyletters to control the naming of the SID 
of the delta to be created. 

For each file processed, get responds (on the standard output) with the SID being 
accessed and with the number of lines retrieved from the SCCS file. 

If the — e keyletter is used, the SID of the delta to be made appears after the SID 
accessed and before the number of lines generated. If there is more than one 
named file or if a directory or standard input is named, each file name is printed 
(preceded by a new-line) before it is processed. If the — i keyletter is used 
included deltas are listed following the notation "Included"; if the — x keyletter 
is used, excluded deltas are listed following the notation "Excluded". 
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TABLE 1. Determination of SCCS Identification String 



SID* 

Specified 


— b Keyletter 
Usedj 


Other 

Conditions 


SID 

Retrieved 


SID of Delta 
to be Created 


nonef 


no 


R defaults to mR 


mR.mL 


mR.(mL+l) 


nonef 


yes 


R defaults to mR 


mR.mL 


mR.mL.(mB+l).l 


R 


no 


R > mR 


mR.mL 


p 2*** 


R 


no 


R = mR 


mR.mL 


mR.(mL+l) 


R 


yes 


R > mR 


mR.mL 


mR.mL.(mB+l).l 


R 


yes 


R = mR 


mR.mL 


mR.mL.(mB+l).l 


R 




R < mR and 
R does not exist 


hR.mL** 


hR.mL.(mB+l).l 






Trunk succ.# 






R 




in release > R 
and R exists 


R.mL 


R.mL.(mB+l).l 


R.L 


no 


No trunk succ. 


R.L 


R.(L+1) 


R.L 


yes 


No trunk succ. 


R.L 


R.L.(mB+l).l 


R.L 


- 


Trunk succ. 
in release > R 


R.L 


R.L.(mB+l).l 


R.L.B 


no 


No branch succ. 


R.L.B.mS 


R.L.B. (mS+1) 


R.L.B 


yes 


No branch succ. 


R.L.B.mS 


R.L.(mB+l).l 


R.L.B.S 


no 


No branch succ. 


R.L.B.S 


R.L.B. (S+l) 


R.L.B.S 


yes 


No branch succ. 


R.L.B.S 


R.L.(mB+l).l 


R.L.B.S 


- 


Branch succ. 


R.L.B.S 


R.L.(mB+l).l 


* 


"R", "L", "B", 


and "S" are the 


"release", "level' 


', "branch", and 



"sequence" components of the SID, respectively; "m" means "maximum". 
Thus, for example, "R.mL" means "the maximum level number within 
release R"; "R.L.(mB+l).l" means "the first sequence number on the new 
branch (i.e., maximum branch number plus one) of level L within release 
R". Note that if the SID specified is of the form "R.L", "R.L.B", or 
"R.L.B.S", each of the specified components must exist. 

** "hR" is the highest existing release that is lower than the specified, nonex- 
istent, release R. 

*** This is used to force creation of the first delta in a new release. 

# Successor. 

| The — b keyletter is effective only if the b flag [see admin( 1)] is present in 
the file. An entry of — means "irrelevant". 

J This case applies if the d (default SID) flag is not present in the file. If the 
d flag is present in the file, then the SID obtained from the d flag is inter- 
preted as if it had been specified on the command line. Thus, one of the 
other cases in this table applies. 

IDENTIFICATION KEYWORDS 

Identifying information is inserted into the text retrieved from the SCCS file by 
replacing identification keywords with their value wherever they occur. The fol- 
lowing keywords may be used in the text stored in an SCCS file: 
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Keyword Value 

%M% Module name: either the value of the m flag in the file [see admin( 1)], 
or if absent, the name of the SCCS file with the leading s. removed. 

%I% SCCS identification (SID) (%R%.%L%.%B%.%S%) of the retrieved 
text. 

%R% Release. 

%L% Level. 

%B% Branch. 

%S% Sequence. 

%D% Current date (YY/MM/DD). 

%H% Current date (MM/DD/YY). 

%T% Current time (HH:MM:SS). 

%E% Date newest applied delta was created (YY/MM/DD). 

%G% Date newest applied delta was created (MM/DD/YY). 

%U% Time newest applied delta was created (HH:MM:SS). 

%Y% Module type: value of the t flag in the SCCS file [see admin ( 1)]. 

%F% SCCS file name. 

%P% Fully qualified SCCS file name. 

%Q% The value of the q flag in the file [see admin( 1)]. 

%C% Current line number. This keyword is intended for identifying mes- 

sages output by the program such as "this should not have hap- 
pened" type errors. It is not intended to be used on every line to 
provide sequence numbers. 

%Z% The 4-character string @(#) recognizable by what{ 1). 

%W% A shorthand notation for constructing what{ 1) strings for UNIX system 
program files. %W% = %Z%%M%<horizontal-tab>%I% 

%A% Another shorthand notation for constructing what( 1) strings for non- 
UNIX system program files. 

%A% = %Z%%Y% %M% %I%%Z% 



Several auxiliary files may be created by get. These files are known generically 
as the g-file, l-file, p-file, and z-file. The letter before the hyphen is called the 
tag. An auxiliary file name is formed from the SCCS file name: the last com- 
ponent of all SCCS file names must be of the form s .module-name, the auxiliary 
files are named by replacing the leading s with the tag. The g-file is an excep- 
tion to this scheme: the g-file is named by removing the s. prefix. For example, 
s.xyz.c, the auxiliary file names would be xyz.c, l.xyz.c, p.xyz.c, and z.xyz.c, 
respectively. 

The g-file, which contains the generated text, is created in the current directory 
(unless the — p keyletter is used). A g-file is created in all cases, whether or not 
any lines of text were generated by the get. It is owned by the real user. If the 
— k keyletter is used or implied its mode is 644; otherwise its mode is 444. Only 
the real user need have write permission in the current directory. 

The l-file contains a table showing which deltas were applied in generating the 
retrieved text. The l-file is created in the current directory if the —1 keyletter is 
used; its mode is 444 and it is owned by the real user. Only the real user need 
have write permission in the current directory. 

Lines in the l-file have the following format: 
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a. A blank character if the delta was applied; 

* otherwise. 

b. A blank character if the delta was applied or was not applied 
and ignored; 

* if the delta was not applied and was not ignored. 

c. A code indicating a "special" reason why the delta was or was 
not applied: 

"I": Included. 

"X": Excluded. 

"C": Cut off (by a — c keyletter). 

d. Blank. 

e. SCCS identification (SID). 

f. Tab character. 

g. Date and time (in the form YY/MM/DD HH:MM:SS) of creation. 

h. Blank. 

i. Login name of person who created delta. 

The comments and MR data follow on subsequent lines, indented one 
horizontal tab character. A blank line terminates each entry. 

The p-file is used to pass information resulting from a get with an — e keyletter 
along to delta. Its contents are also used to prevent a subsequent execution of 
get with an —e keyletter for the same SID until delta is executed or the joint edit 
flag, j, [see admin( 1)] is set in the SCCS file. The p-file is created in the directory 
containing the SCCS file and the effective user must have write permission in 
that directory. Its mode is 644 and it is owned by the effective user. The format 
of the p-file is: the gotten SID, followed by a blank, followed by the SID that the 
new delta will have when it is made, followed by a blank, followed by the login 
name of the real user, followed by a blank, followed by the date-time the get 
was executed, followed by a blank and the — i keyletter argument if it was 
present, followed by a blank and the -x keyletter argument if it was present, 
followed by a new-line. There can be an arbitrary number of lines in the p-file 
at any time; no two lines can have the same new delta SID. 

The z-file serves as a lock-out mechanism against simultaneous updates. Its con- 
tents are the binary (2 bytes) process ID of the command (i.e., get) that created it. 
The z-file is created in the directory containing the SCCS file for the duration of 
get. The same protection restrictions as those for the p-file apply for the z-file. 
The z-file is created mode 444. 

FILES 

g-file Existed before the execution of delta ; removed after completion 

of delta. 

p-file Existed before the execution of delta ; may exist after completion 

of delta. 

q-file Created during the execution of delta; removed after completion 

of delta. 

x-file Created during the execution of delta; renamed to SCCS file 

after completion of delta. 

z-file Created during the execution of delta; removed during the exe- 

cution of delta. 
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d-file Created during the execution of delta; removed after completion 

of delta. 

/usr/bin/bdiff Program to compute differences between the "gotten" file and 
the g-file. 

SEE ALSO 

admin(l), delta(l), prs(l), what(l). 
help(l) in the User's Reference Manual. 

DIAGNOSTICS 

Use help( 1) for explanations. 

BUGS 

If the effective user has write permission (either explicitly or implicitly) in the 
directory containing the SCCS files, but the real user does not, then only one file 
may be named when the — e keyletter is used. 
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NAME 

infocmp — compare or print out terminfo descriptions 
SYNOPSIS 

infocmp [-d] [— c] [-n] [-1] [-L] [-C] [-r] [-u] [-s d|i|l|c] [-v] [-V] [-1] 
[^w width] [—A directory] [— B directory] [termname ...] 

DESCRIPTION 

infocmp can be used to compare a binary terminfo (4) entry with other terminfo 
entries, rewrite a terminfo (4) description to take advantage of the use= terminfo 
field, or print out a terminfo( 4) description from the binary file (term( 4)) in a 
variety of formats. In all cases, the boolean fields will be printed first, followed 
by the numeric fields, followed by the string fields. 

Default Options 

If no options are specified and zero or one termnames are specified, the —I option 
will be assumed. If more than one termname is specified, the — d option will be 
assumed. 

Comparison Options [— d] [—c] [— n] 

infocmp compares the terminfo ( 4) description of the first terminal termname with 
each of the descriptions given by the entries for the other terminal's termnames. 
If a capability is defined for only one of the terminals, the value returned will 
depend on the type of the capability: F for boolean variables, — 1 for integer vari- 
ables, and NULL for string variables. 

— d produce a list of each capability that is different. In this manner, if one 

has two entries for the same terminal or similar terminals, using infocmp 
will show what is different between the two entries. This is sometimes 
necessary when more than one person produces an entry for the same 
terminal and one wants to see what is different between the two. 

—c produce a list of each capability that is common between the two 
entries. Capabilities that are not set are ignored. This option can be 
used as a quick check to see if the — u option is worth using. 

— n produce a list of each capability that is in neither entry. If no term- 

names are given, the environment variable TERM will be used for both 
of the termnames. This can be used as a quick check to see if anything 
was left out of the description. 

Source Listing Options [—1] [— L] [— C] [—r] 

The —I, — L, and — C options will produce a source listing for each terminal 
named. 

—I use the terminfo( 4) names 

— L use the long C variable name listed in <term.h> 

-C use the termcap names 

— r when using — C, put out all capabilities in termcap form 

If no termnames are given, the environment variable TERM will be used for the 
terminal name. 
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The source produced by the — C option may be used directly as a termcap entry, 
but not all of the parameterized strings may be changed to the termcap format. 
infocmp will attempt to convert most of the parameterized information, but that 
which it doesn't will be plainly marked in the output and commented out. 
These should be edited by hand. 

All padding information for strings will be collected together and placed at the 
beginning of the string where termcap expects it. Mandatory padding (padding 
information with a trailing '/') will become optional. 

All termcap variables no longer supported by terminfo( 4), but which are derivable 
from other terminfo( 4) variables, will be output. Not all terminfo( 4) capabilities 
will be translated; only those variables which were part of termcap will normally 
be output. Specifying the — r option will take off this restriction, allowing all 
capabilities to be output in termcap form. 

Note that because padding is collected to the beginning of the capability, not all 
capabilities are output, mandatory padding is not supported, and termcap strings 
were not as flexible, it is not always possible to convert a terminfo( 4) string capa- 
bility into an equivalent termcap format. Not all of these strings will be able to 
be converted. A subsequent conversion of the termcap file back into terminfo( 4) 
format will not necessarily reproduce the original terminfo{ 4) source. 

Some common terminfo parameter sequences, their termcap equivalents, and 
some terminal types which commonly have such sequences, are: 



Terminfo 


Termcap 


Representative Terminals 


%pl%c 


%. 


adm 


%pl%d 

%pl%'x'%+%c 


%d 


hp, ANSI standard, vtlOO 


%+x 


concept 


%i 


%i 


ANSI standard, vtlOO 


%pl %?%'x'% > %t%pl %'y' %+%; 


%>xy 


concept 


%p2 is printed before %pl 


%r 


h P 



Use* Option [— u] 

— u produce a terminfo ( 4) source description of the first terminal termname 
which is relative to the sum of the descriptions given by the entries for 
the other terminals termnames. It does this by analyzing the differences 
between the first termname and the other termnames and producing a 
description with use= fields for the other terminals. In this manner, it 
is possible to retrofit generic terminfo entries into a terminal's descrip- 
tion. Or, if two similar terminals exist, but were coded at different 
times or by different people so that each description is a full descrip- 
tion, using infocmp will show what can be done to change one descrip- 
tion to be relative to the other. 

A capability will get printed with an at-sign (@) if it no longer exists in the first 
termname, but one of the other termname entries contains a value for it. A capa- 
bility's value gets printed if the value in the first termname is not found in any of 
the other termname entries, or if the first of the other termname entries that has 
this capability gives a different value for the capability than that in the first term- 
name. 
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The order of the other termname entries is significant. Since the terminfo com- 
piler tic(lM) does a left-to-right scan of the capabilities, specifying two use= 
entries that contain differing entries for the same capabilities will produce 
different results depending on the order that the entries are given in. infocmp 
will flag any such inconsistencies between the other termname entries as they are 
found. 

Alternatively, specifying a capability after a use= entry that contains that capa- 
bility will cause the second specification to be ignored. Using infocmp to recreate 
a description can be a useful check to make sure that everything was specified 
correctly in the original source description. 

Another error that does not cause incorrect compiled files, but will slow down 
the compilation time, is specifying extra use= fields that are superfluous. 
infocmp will flag any other termname use= fields that were not needed. 

Other Options [— s d|i|l|c] [— v] [—V] [—1] [— w width] 

— s sort the fields within each type according to the argument below: 

d leave fields in the order that they are stored in the terminfo data- 
base. 

i sort by terminfo name. 

1 sort by the long C variable name, 
c sort by the termcap name. 

If no — s option is given, the fields printed out will be sorted alphabeti- 
cally by the terminfo name within each type, except in the case of the 
— C or the — L options, which cause the sorting to be done by the 
termcap name or the long C variable name, respectively. 

— v print out tracing information on standard error as the program runs. 

—V print out the version of the program in use on standard error and exit. 

— 1 cause the fields to printed out one to a line. Otherwise, the fields will 
be printed several to a line to a maximum width of 60 characters. 

— w change the output to width characters. 

Changing Databases [—A directory] [— B directory] 

The location of the compiled terminfo( 4) database is taken from the environment 
variable TERMINFO. If the variable is not defined, or the terminal is not found 
in that location, the system terminfo( 4) database, usually in /usr/ lib /terminfo, 
will be used. The options —A and — B may be used to override this location. 
The —A option will set TERMINFO for the first termname and the — B option will 
set TERMINFO for the other termnames . With this, it is possible to compare 
descriptions for a terminal with the same name located in two different data- 
bases. This is useful for comparing descriptions for the same terminal created by 
different people. Otherwise the terminals would have to be named differently in 
the terminfo( 4) database for a comparison to be made. 

FILES 

/usr/lib/terminfo/?/* compiled terminal description database 
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DIAGNOSTICS 

malloc is out of space! 

There was not enough memory available to process all the ter- 
minal descriptions requested. Run infocmp several times, each 
time including a subset of the desired termnames. 

use= order dependency found: 

A value specified in one relative terminal specification was 
different from that in another relative terminal specification. 

'us enterin' did not add anything to the description. 

A relative terminal name did not contribute anything to the 
final description, 

must have at least two terminal names for a comparison to be done. 

The — u, —d and — c options require at least two terminal 
names. 



SEE ALSO 

tic(lM), curses(3X), term(4), terminfo(4) in the Programmer's Reference Manual. 
captoinfo(lM) in the System Administrator's Reference Manual. 

Chapter 10 of the Programmer's Guide. 

NOTE 

The termcap database (from earlier releases of UNIX System V) may not be sup- 
plied in future releases. 
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NAME 

install — install commands 



SYNOPSIS 

/etc/install [— c dira] [— f dirb] [— i] [— n dire] [-m mode] [— u user] [— g 
group] [— o] [— s] file [dirx ...] 

DESCRIPTION 

The install command is most commonly used in '"makefiles" [See make( 1)] to 
install a file (updated target file) in a specific place within a file system. Each file 
is installed by copying it into the appropriate directory, thereby retaining the 
mode and owner of the original command. The program prints messages telling 
the user exactly what files it is replacing or creating and where they are going. 

If no options or directories ( dirx . . .) are given, install will search a set of default 
directories (/bin, /usr/bin, /etc, /lib, and /usr/lib, in that order) for a file 
with the same name as file. When the first occurrence is found, install issues a 
message saying that it is overwriting that file with file, and proceeds to do so. If 
the file is not found, the program states this and exits without further action. 

If one or more directories (dirx . . .) are specified after file, those directories will 
be searched before the directories specified in the default list. 



The meanings of the options are: 



— c dira 



— f dirb 



— n dire 



— m mode 
— u user 
“g group 



Installs a new command (file) in the directory specified by 
dira, only if it is not found. If it is found, install issues a 
message saying that the file already exists, and exits 
without overwriting it. May be used alone or with the — s 
option. 

Forces file to be installed in given directory, whether or 
not one already exists. If the file being installed does not 
already exist, the mode and owner of the new file will be 
set to 755 and bin, respectively. If the file already exists, 
the mode and owner will be that of the already existing 
file. May be used alone or with the — o or — s options. 

Ignores default directory list, searching only through the 
given directories (dirx . . .). May be used alone or with any 
other options except — c and — f. 

If file is not found in any of the searched directories, it is 
put in the directory specified in dire. The mode and 
owner of the new file will be set to 755 and bin, respec- 
tively. May be used alone or with any other options 
except — c and — f. 

The mode of the new file is set to mode. Only available to 
the superuser. 

The owner of the new file is set to user. Only available to 
the superuser. 

The group id of the new file is set to group. Only avail- 
able to the superuser. 
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-s 

SEE ALSO 

make(l). 
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If file is found, this option saves the "found" file by 
copying it to OLDfile in the directory in which it was 
found. This option is useful when installing a frequently 
used file such as /bin/sh or /etc/getty, where the existing 
file cannot be removed. May be used alone or with any 
other options except —c. 

Suppresses printing of messages other than error mes- 
sages. May be used alone or with any other options. 




LD(1) 



(Software Generation System Utilities) 



LD(1) 



NAME 

Id — link editor for common object files 
SYNOPSIS 

Id [options] filename 
DESCRIPTION 

The Id command combines several object files into one, performs relocation, 
resolves external symbols, and supports symbol table information for symbolic 
debugging. In the simplest case, the names of several object programs are given, 
and Id combines the objects, producing an object module that can either be exe- 
cuted or, if the — r option is specified, used as input for a subsequent Id run. The 
output of Id is left in a.out. By default this file is executable if no errors 
occurred during the load. If any input file, filename, is not an object file. Id 
assumes it is either an archive library or a text file containing link editor direc- 
tives. [See Link Editor Directives in the UNIX System V Programmer's Guide for a 
discussion of input directives.] 

If any argument is a library, it is searched exactly once at the point it is encoun- 
tered in the argument list. The library may be either a relocatable archive 
library or a shared library. [See Shared Libraries in the UNIX System V Pro- 
grammer's Guide for a discussion of shared libraries.] Only those routines 
defining an unresolved external reference are loaded. The library (archive) 
symbol table [see ar( 4)] is searched sequentially with as many passes as are 
necessary to resolve external references which can be satisfied by library 
members. Thus, the ordering of library members is functionally unimportant, 
unless there exist multiple library members defining the same external symbol. 

The following options are recognized by Id: 

— e epsym 

Set the default entry point address for the output file to be that of the 
symbol epsym. 

— f fill Set the default fill pattern for "holes" within an output section as well as 
initialized bss sections. The argument fill is a two-byte constant. 

—lx Search a library libx.a, where x is up to nine characters. A library is 
searched when its name is encountered, so the placement of a —1 is 
significant. By default, libraries are located in LIBDIR or LLIBDIR. 

— m Produce a map or listing of the input/output sections on the standard 
output. 

— o outfile 

Produce an output object file by the name outfile. The name of the 
default object file is a.out. 

— r Retain relocation entries in the output object file. Relocation entries 

must be saved if the output file is to become an input file in a subse- 
quent Id run. The link editor will not complain about unresolved refer- 
ences, and the output file will not be executable. 

—a Create an absolute file. This is the default if the — r option is not used. 
Used with the — r option, —a allocates memory for common symbols. 
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— s Strip line number entries and symbol table information from the output 

object file. 

— t Turn off the warning about multiply-defined symbols that are not the 

same size. 

— u symname 

Enter symname as an undefined symbol in the symbol table. This is 
useful for loading entirely from a library, since initially the symbol table 
is empty and an unresolved reference is needed to force the loading of 
the first routine. The placement of this option on the Id line is 
significant; it must be placed before the library which will define the 
symbol. 

—x Do not preserve local symbols in the output symbol table; enter external 
and static symbols only. This option saves some space in the output 
file. 

— z Do not bind anything to address zero. This option will allow runtime 

detection of null pointers. 

— L dir Change the algorithm of searching for libx.a to look in dir before 
looking in LIBDIR and LL1BD1R. This option is effective only if it pre- 
cedes the —1 option on the command line. 

— M Output a message for each multiply-defined external definition. 

— N Put the text section at the beginning of the text segment rather than after 
all header information, and put the data section immediately following 
text in the core image. 

—V Output a message giving information about the version of Id being used. 
-VS num 

Use num as a decimal version stamp identifying the a.out file that is pro- 
duced. The version stamp is stored in the optional header. 

-Y [LU],dir 

Change the default directory used for finding libraries. If L is specified 
the first default directory which Id searches, LIBDIR, is replaced by dir. 
If U is specified and Id has been built with a second default directory, 
LLIBDIR, then that directory is replaced by dir. If Id was built with only 
one default directory and U is specified a warning is printed and the 
option is ignored. 

FILES 

LIBDIR/ libx.a 
LLIBDIR/ libx.a 
a.out 
LIBDIR 
LLIBDIR 

SEE ALSO 

as(l), cc(l), mkshlib(l), exit(2), end(3C), a.out(4), ar(4), and Link Editor Directives 
and Shared Libraries in the Programmer's Guide. 



libraries 
libraries 
output file 
usually /lib 
usually /usr/lib 
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CAVEATS 

Through its options and input directives, the common link editor gives users 
great flexibility; however, those who use the input directives must assume some 
added responsibilities. Input directives and options should insure the following 
properties for programs: 

— C defines a zero pointer as null. A pointer to which zero has been 
assigned must not point to any object. To satisfy this, users must not place 
any object at virtual address zero in the program's address space. 

— When the link editor is called through cc(l), a startup routine is linked 
with the user's program. This routine calls exit( ) [see exit( 2)] after execu- 
tion of the main program. If the user calls the link editor directly, then the 
user must insure that the program always calls exit( ) rather than falling 
through the end of the entry routine. 

The symbols etext, edata, and end [see end( 3C)] are reserved and are defined by 
the link editor. It is incorrect for a user program to redefine them. 

If the link editor does not recognize an input file as an object file or an archive 
file, it will assume that it contains link editor directives and will attempt to parse 
it. This will occasionally produce an error message complaining about "syntax 
errors". 

Arithmetic expressions may only have one forward referenced symbol per 
expression. 
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NAME 

lex — generate programs for simple lexical tasks 
SYNOPSIS 

lex [ — rctvn ] [ file ] ... 

DESCRIPTION 

The lex command generates programs to be used in simple lexical analysis of 
text. 

The input files (standard input default) contain strings and expressions to be 
searched for, and C text to be executed when strings are found. 

A file lex.yy.c is generated which, when loaded with the library, copies the 
input to the output except when a string specified in the file is found; then the 
corresponding program text is executed. The actual string matched is left in 
yytext, an external character array. Matching is done in order of the strings in 
the file. The strings may contain square brackets to indicate character classes, as 
in [abx— z] to indicate a, b, x, y, and z; and the operators *, +, and ? mean 
respectively any non -negative number of, any positive number of, and either 
zero or one occurrence of, the previous character or character class. The char- 
acter . is the class of all ASCII characters except new-line. Parentheses for 
grouping and vertical bar for alternation are also supported. The notation r{d,e] 
in a rule indicates between d and e instances of regular expression r. It has 
higher precedence than [ but lower than *, ?, +, and concatenation. Thus 
[a— zA— Z]+ matches a string of letters. The character * at the beginning of an 
expression permits a successful match only immediately after a new-line, and 
the character $ at the end of an expression requires a trailing new-line. The 
character / in an expression indicates trailing context; only the part of the 
expression up to the slash is returned in yytext, but the remainder of the expres- 
sion must follow in the input stream. An operator character may be used as an 
ordinary symbol if it is within " symbols or preceded by \. 

Three subroutines defined as macros are expected: inputO to read a character; 
unput(c) to replace a character read; and output(c) to place an output character. 
They are defined in terms of the standard streams, but you can override them. 
The program generated is named yylexO, and the library contains a main() 
which calls it. The action REJECT on the right side of the rule causes this match 
to be rejected and the next suitable match executed; the function yymoreO accu- 
mulates additional characters into the same yytext; and the function yyless(p) 
pushes back the portion of the string matched beginning at p, which should be 
between yytext and yytext+yyleng. The macros input and output use files yyin 
and yyout to read from and write to, defaulted to stdin and stdout, respectively. 

Any line beginning with a blank is assumed to contain only C text and is 
copied; if it precedes %% it is copied into the external definition area of the 
lex.yy.c file. All rules should follow a %%, as in YACC. Lines preceding %% 
which begin with a non-blank character define the string on the left to be the 
remainder of the line; it can be called out later by surrounding it with {}. Note 
that curly brackets do not imply parentheses; only string substitution is done. 
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EXAMPLE 

D [0-9] 

%% 

if printf("IF statement\n"); 

[a— z]+ printf("tag, value %s\n",yytext); 

0{D}+ printf ("octal number %s\n",yytext); 

{D} + printf ("decimal number %s\n",yytext); 

"++" printf(”unary op\n"); 

"+" printf("binary op\n"); 

"/*" skipcommnts(); 

%% 

skipcommnts() 
for (;;) 

while (input() != '*') 

if (input() !- '/') 

unput(yy text[yyleng- 1 ]); 

else 

return; 

} 

} 

The external names generated by lex all begin with the prefix yy or YY. 

The flags must appear before any files. The flag — r indicates RATFOR actions, 
— c indicates C actions and is the default, — t causes the lex.yy.c program to be 
written instead to standard output, — v provides a one-line summary of statistics, 
— n will not print out the — v summary. Multiple files are treated as a single file. 
If no files are specified, standard input is used. 

Certain table sizes for the resulting finite state machine can be set in the 
definitions section: 

%p n number of positions is n (default 2500) 

%n n number of states is n (500) 

%e n number of parse tree nodes is n (1000) 

%a n number of transitions is n (2000) 

%k n number of packed character classes is n (1000) 

%o n size of output array is n (3000) 

The use of one or more of the above automatically implies the — v option, unless 
the — n option is used. 

SEE ALSO 

yacc(l). 

Programmer's Guide. 

BUGS 

The — r option is not yet fully operational. 
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NAME 

lint — a C program checker 
SYNOPSIS 

lint [ option ] ... file ... 

DESCRIPTION 

The lint command attempts to detect features of the C program files that are 
likely to be bugs, non-portable, or wasteful. It also checks type usage more 
strictly than the compilers. Among the things that are currently detected are 
unreachable statements, loops not entered at the top, automatic variables 
declared and not used, and logical expressions whose value is constant. More- 
over, the usage of functions is checked to find functions that return values in 
some places and not in others, functions called with varying numbers or types of 
arguments, and functions whose values are not used or whose values are used 
but none returned. 

Arguments whose names end with .c are taken to be C source files. Arguments 
whose names end with .In are taken to be the result of an earlier invocation of 
lint with either the — c or the — o option used. The .In files are analogous to .o 
(object) files that are produced by the cc( 1) command when given a .c file as 
input. Files with other suffixes are warned about and ignored. 

lint will take all the .c, .In, and Ilib-lx.In (specified by — Lt) files and process 
them in their command line order. By default, lint appends the standard C lint 
library (Ilib-lc.ln) to the end of the list of files. However, if the — p option is 
used, the portable C lint library (llib-port.ln) is appended instead. When the —c 
option is not used, the second pass of lint checks this list of files for mutual 
compatibility. When the — c option is used, the .In and the llib-bc.ln files are 
ignored. 

Any number of lint options may be used, in any order, intermixed with file- 
name arguments. The following options are used to suppress certain kinds of 
complaints: 

—a Suppress complaints about assignments of long values to variables that 
are not long. 

— b Suppress complaints about break statements that cannot be reached. 

(Programs produced by lex or yacc will often result in many such com- 
plaints). 

— h Do not apply heuristic tests that attempt to intuit bugs, improve style, 

and reduce waste. 

— u Suppress complaints about functions and external variables used and not 

defined, or defined and not used. (This option is suitable for running 
lint on a subset of files of a larger program). 

—v Suppress complaints about unused arguments in functions. 

—x Do not report variables referred to by external declarations but never 
used. 
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The following arguments alter lint's behavior: 

—lx Include additional lint library llib-lx.ln. For example, you can include a 
lint version of the math library llib-lm.ln by inserting — lm on the com- 
mand line. This argument does not suppress the default use of llib- 
lc.ln. These lint libraries must be in the assumed directory. This option 
can be used to reference local lint libraries and is useful in the develop- 
ment of multi-file projects. 

— n Do not check compatibility against either the standard or the portable 

lint library. 

— p Attempt to check portability to other dialects (IBM and GCOS) of C. 

Along with stricter checking, this option causes all non-external names 
to be truncated to eight characters and all external names to be truncated 
to six characters and one case. 

— c Cause lint to produce a .In file for every .c file on the command line. 

These .In files are the product of lint's first pass only, and are not 
checked for inter-function compatibility. 

— o lib Cause lint to create a lint library with the name Ilib-lZ/fr.ln. The — c 
option nullifies any use of the — o option. The lint library produced is 
the input that is given to lint's second pass. The — o option simply 
causes this file to be saved in the named lint library. To produce a llib- 
llib.ln without extraneous messages, use of the — x option is suggested. 
The —v option is useful if the source file(s) for the lint library are just 
external interfaces (for example, the way the file llib-lc is written). 
These option settings are also available through the use of 'Tint com- 
ments" (see below). 

The — D, — U, and —I options of cpp( 1) and the — g and — O options of cc(l) are 
also recognized as separate arguments. The — g and — O options are ignored, 
but, by recognizing these options, lint's behavior is closer to that of the cc( 1) 
command. Other options are warned about and ignored. The pre-processor 
symbol "lint" is defined to allow certain questionable code to be altered or 
removed for lint. Therefore, the symbol "lint" should be thought of as a 
reserved word for all code that is planned to be checked by lint. 

Certain conventional comments in the C source will change the behavior of lint: 
/ *NOTREACHED* / 

at appropriate points stops comments about unreachable code. 
[This comment is typically placed just after calls to functions like 
exit( 2)\. 

/ * VARARGSn * / 

suppresses the usual checking for variable numbers of arguments 
in the following function declaration. The data types of the first 
n arguments are checked; a missing n is taken to be 0. 

/♦ARGSUSED*/ 

turns on the — v option for the next function. 
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/ *LINTLIBRARY*/ 

at the beginning of a file shuts off complaints about unused 
functions and function arguments in this file. This is equivalent 
to using the -v and -x options. 

lint produces its first output on a per-source-file basis. Complaints regarding 
included files are collected and printed after all source files have been processed. 
Finally, if the — c option is not used, information gathered from all input files is 
collected and checked for consistency. At this point, if it is not clear whether a 
complaint stems from a given source file or from one of its included files, the 
source file name will be printed followed by a question mark. 

The behavior of the — c and the — o options allows for incremental use of lint on 
a set of C source files. Generally, one invokes lint once for each source file with 
the — c option. Each of these invocations produces a .In file which corresponds 
to the .c file, and prints all messages that are about just that source file. After all 
the source files have been separately run through lint , it is invoked once more 
(without the — c option), listing all the .In files with the needed — lx options. 
This will print all the inter- file inconsistencies. This scheme works well with 
make( 1); it allows make to be used to lint only the source files that have been 
modified since the last time the set of source files were linted. 



FILES 

LLIBDIR 

LLIBDIR/ lint[12] 
LLIBDIR /llib-lc.ln 



LLIBDIR /llib-port.ln 

LLIBDIR /llib-lm.ln 

TMPDIR/*lint* 

TMPD1R 



SEE ALSO 



the directory where the lint libraries specified by the —lx 
option must exist, usually /usr/lib 
first and second passes 

declarations for C Library functions (binary format; source 
is in LLIBDIR/ llib-lc ) 

declarations for portable functions (binary format; source 
is in LLIBDIR /llib-port ) 

declarations for Math Library functions (binary format; 

source is in LLIBDIR/ llib-lm ) 

temporaries 

usually /usr/tmp but can be redefined by setting the 
environment variable TMPDIR [see tempnamQ in 
tmpnam( 3S)]. 



cc(l), cpp(l), make(l). 

BUGS 



exit( 2), setjmp (3C), and other functions that do not return are not understood; 
this causes various lies. 
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NAME 

list — produce C source listing from a common object file 
SYNOPSIS 

list [ —V ] [— h] [— F function] source-file . . . [object-file] 

DESCRIPTION 

The list command produces a C source listing with line number information 
attached. If multiple C source files were used to create the object file, list will 
accept multiple file names. The object file is taken to be the last non-C source 
file argument. If no object file is specified, the default object file, a.out, will be 
used. 

Line numbers will be printed for each line marked as breakpoint inserted by the 
compiler (generally, each executable C statement that begins a new line of 
source). Line numbering begins anew for each function. Line number 1 is 
always the line containing the left curly brace ({) that begins the function body. 
Line numbers will also be supplied for inner block redeclarations of local vari- 
ables so that they can be distinguished by the symbolic debugger. 

The following options are interpreted by list and may be given in any order: 

—V Print, on standard error, the version number of the list command 

executing. 

— h Suppress heading output. 

— F function List only the named function. The — F option may be specified 
multiple times on the command line. 

SEE ALSO 

as(l), cc(l), ld(l). 

CAVEATS 

Object files given to list must have been compiled with the — g option of cc(l). 

Since list does not use the C preprocessor, it may be unable to recognize func- 
tion definitions whose syntax has been distorted by the use of C preprocessor 
macro substitutions. 

DIAGNOSTICS 

list will produce the error message 'list: name: cannot open" if name cannot be 
read. If the source file names do not end in .c , the message is "list: name: 
invalid C source name". An invalid object file will cause the message "list: 
name: bad magic" to be produced. If some or all of the symbolic debugging 
information is missing, one of the following messages will be printed: "list: 
name: symbols have been stripped, cannot proceed", "list: name: cannot read 
line numbers", and "list: name: not in symbol table". The following messages 
are produced when list has become confused by #ifdef's in the source file: "list: 
name: cannot find function in symbol table", "list: name: out of sync: too many 
}", and "list: name: unexpected end-of-file". The error message "list: name: 
missing or inappropriate line numbers" means that either symbol debugging 
information is missing, or list has been confused by C preprocessor statements. 
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NAME 

lorder — find ordering relation for an object library 

SYNOPSIS 

lorder file ... 

DESCRIPTION 

The input is one or more object or library archive files [see ar( 1)]. The standard 
output is a list of pairs of object file or archive member names, meaning that the 
first file of the pair refers to external identifiers defined in the second. The 
output may be processed by tsort( 1) to find an ordering of a library suitable for 
one-pass access by ld( 1). Note that the link editor ld( 1) is capable of multiple 
passes over an archive in the portable archive format [see ar(4)] and does not 
require that lorder ( 1) be used when building an archive. The usage of the 
lorder (1) command may, however, allow for a slightly more efficient access of 
the archive during the link edit process. 

The following example builds a new library from existing .o files, 
ar — cr library 'lorder *.o | tsort' 

FILES 

TMPDIR /* symref temporary files 

TMPDIR /* symdef temporary files 

TMPDIR is usually /usr/tmp but can be redefined by setting the environment 
variable TMPDIR [see tempnamQ in tmpnam( 3S)]. 

SEE ALSO 

ar(l), ld(l), tsort(l), ar(4). 

CAVEAT 

lorder will accept as input any object or archive file, regardless of its suffix, pro- 
vided there is more than one input file. If there is but a single input file, its 
suffix must be .o. 
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NAME 

m4 — macro processor 
SYNOPSIS 

m4 [ options ] [ files ] 

DESCRIPTION 

The m4 command is a macro processor intended as a front end for Ratfor, C, 
and other languages. Each of the argument files is processed in order; if there 
are no files, or if a file name is — , the standard input is read. The processed text 
is written on the standard output. 

The options and their effects are as follows: 

— e Operate interactively. Interrupts are ignored and the output is 

unbuffered. 

— s Enable line sync output for the C preprocessor (#line . . . ) 

—Bint Change the size of the push-back and argument collection buffers from 
the default of 4,096. 

— H int Change the size of the symbol table hash array from the default of 199. 
The size should be prime. 

—Sint Change the size of the call stack from the default of 100 slots. Macros 
take three slots, and non-macro arguments take one. 

—Tint Change the size of the token buffer from the default of 512 bytes. 

To be effective, these flags must appear before any file names and before any 
— D or — U flags: 

— D name[=val] 

Defines name to val or to null in val's absence, 

— U name 

undefines name. 

Macro calls have the form: 

name(argl,arg2, ..., argn) 

The ( must immediately follow the name of the macro. If the name of a defined 
macro is not followed by a (, it is deemed to be a call of that macro with no 
arguments. Potential macro names consist of alphabetic letters, digits, and 
underscore where the first character is not a digit. 

Leading unquoted blanks, tabs, and new-lines are ignored while collecting argu- 
ments. Left and right single quotes are used to quote strings. The value of a 
quoted string is the string stripped of the quotes. 

When a macro name is recognized, its arguments are collected by searching for a 
matching right parenthesis, If fewer arguments are supplied than are in the 
macro definition, the trailing arguments are taken to be null. Macro evaluation 
proceeds normally during the collection of the arguments, and any commas or 
right parentheses which happen to turn up within the value of a nested call are 
as effective as those in the original input text. After argument collection, the 
value of the macro is pushed back onto the input stream and rescanned. 
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mi makes available the following built-in macros. They may be redefined, but 
once this is done the original meaning is lost. Their values are null unless oth- 
erwise stated. 



define 



undefine 

defn 

pushdef 

popdef 

ifdef 

shift 

changequote 

changecom 



divert 



undivert 

divnum 

dnl 



the second argument is installed as the value of the macro whose 
name is the first argument. Each occurrence of $n in the replace- 
ment text, where n is a digit, is replaced by the n-th argument. 
Argument 0 is the name of the macro; missing arguments are 
replaced by the null string; $# is replaced by the number of argu- 
ments; $* is replaced by a list of all the arguments separated by 
commas; $@ is like $*, but each argument is quoted (with the 
current quotes). 

removes the definition of the macro named in its argument. 

returns the quoted definition of its argument(s). It is useful for 
renaming macros, especially built-ins. 

like define, but saves any previous definition. 

removes current definition of its argument(s), exposing the pre- 
vious one, if any. 

if the first argument is defined, the value is the second argument, 
otherwise the third. If there is no third argument, the value is 
null. The word unix is predefined on UNIX system versions of mi. 

returns all but its first argument. The other arguments are quoted 
and pushed back with commas in between. The quoting nullifies 
the effect of the extra scan that will subsequently be performed. 

change quote symbols to the first and second arguments. The 
symbols may be up to five characters long. Changequote without 
arguments restores the original values (i.e., ' '). 

change left and right comment markers from the default # and 
new-line. With no arguments, the comment mechanism is 
effectively disabled. With one argument, the left marker becomes 
the argument and the right marker becomes new-line. With two 
arguments, both markers are affected. Comment markers may be 
up to five characters long. 

mi maintains 10 output streams, numbered 0-9. The final output 
is the concatenation of the streams in numerical order; initially 
stream 0 is the current stream. The divert macro changes the 
current output stream to its (digit-string) argument. Output 
diverted to a stream other than 0 through 9 is discarded. 

causes immediate output of text from diversions named as argu- 
ments, or all diversions if no argument. Text may be undiverted 
into another diversion. Undiverting discards the diverted text. 

returns the value of the current output stream. 

reads and discards characters up to and including the next new- 
line. 
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ifelse 



incr 



deer 

eval 



len 

index 

substr 



translit 



include 

sinclude 

sysemd 

sysval 

maketemp 

m4exit 

m4wrap 

errprint 

dumpdef 



has three or more arguments. If the first argument is the same 
string as the second, then the value is the third argument. If not, 
and if there are more than four arguments, the process is repeated 
with arguments 4, 5, 6 and 7. Otherwise, the value is either the 
fourth string, or, if it is not present, null. 

returns the value of its argument incremented by 1. The value of 
the argument is calculated by interpreting an initial digit-string as 
a decimal number. 

returns the value of its argument decremented by 1. 

evaluates its argument as an arithmetic expression, using 32-bit 
arithmetic. Operators include +, — , *, /, %, * (exponentiation), 
bitwise &, |, ", and relational; parentheses. Octal and hex 
numbers may be specified as in C. The second argument specifies 
the radix for the result; the default is 10. The third argument may 
be used to specify the minimum number of digits in the result. 

returns the number of characters in its argument. 

returns the position in its first argument where the second argu- 
ment begins (zero origin), or —1 if the second argument does not 
occur. 

returns a substring of its first argument. The second argument is a 
zero origin number selecting the first character; the third argument 
indicates the length of the substring. A missing third argument is 
taken to be large enough to extend to the end of the first string. 

transliterates the characters in its first argument from the set given 
by the second argument to the set given by the third. No abbre- 
viations are permitted. 

returns the contents of the file named in the argument. 

is identical to include, except that it says nothing if the file is inac- 
cessible. 

executes the UNIX system command given in the first argument. 
No value is returned. 

is the return code from the last call to sysemd. 

fills in a string of XXXXX in its argument with the current process 
ID. 

causes immediate exit from m4. Argument 1, if given, is the exit 
code; the default is 0. 

argument 1 will be pushed back at final EOF; example: 
m4wrap('cleanup ( ) ') 

prints its argument on the diagnostic output file. 

prints current names and definitions, for the named items, or for 
all if no arguments are given. 
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traceon with no arguments, turns on tracing for all macros (including 

built-ins). Otherwise, turns on tracing for named macros. 

traceoff turns off trace globally and for any macros specified. Macros 
specifically traced by traceon can be untraced only by specific calls 
to traceoff. 

SEE ALSO 

cc(l), cpp(l). 

The m4 Macro Processor in the Support Tools Guide. 
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NAME 

make — maintain, update, and regenerate groups of programs 
SYNOPSIS 

make [-f makefile] [-p] [-i] [-k] [-s] [-r] [-n] [-b] [-e] [-u] [-1] [-q] 
[names] 

DESCRIPTION 

The make command allows the programmer to maintain, update, and regenerate 
groups of computer programs. The following is a brief description of all options 
and some special names: 

— f makefile Description file name, makefile is assumed to be the name of a 
description file. 

— p Print out the complete set of macro definitions and target descrip- 

tions. 

— i Ignore error codes returned by invoked commands. This mode is 

entered if the fake target name .IGNORE appears in the description 
file. 

— k Abandon work on the current entry if it fails, but continue on other 

branches that do not depend on that entry. 

— s Silent mode. Do not print command lines before executing. This 

mode is also entered if the fake target name .SILENT appears in the 
description file. 

— r Do not use the built-in rules. 

— n No execute mode. Print commands, but do not execute them. 

Even lines beginning with an @ are printed. 

— b Compatibility mode for old makefiles. 

— e Environment variables override assignments within makefiles. 

— u Force an unconditional update. 

— t Touch the target files (causing them to be up-to-date) rather than 

issue the usual commands. 

— q Question. The make command returns a zero or non-zero status 

code depending on whether the target file is or is not up-to-date. 

.DEFAULT If a file must be made but there are no explicit commands or 
relevant built-in rules, the commands associated with the name 
.DEFAULT are used if it exists. 

.PRECIOUS Dependents of this target will not be removed when quit or inter- 
rupt are hit. 

.SILENT Same effect as the — s option. 

.IGNORE Same effect as the — i option. 

make executes commands in makefile to update one or more target names. Name 
is typically a program. If no — f option is present, makefile. Makefile, and the 
Source Code Control System(SCCS) files s.makefile, and s.Makefile are tried in 
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order. If makefile is — , the standard input is taken. More than one - makefile 
argument pair may appear. 

make updates a target only if its dependents are newer than the target (unless 
the — u option is used to force an unconditional update). All prerequisite files of 
a target are added recursively to the list of targets. Missing files are deemed to 
be out-of-date. 

makefile contains a sequence of entries that specify dependencies. The first line 
of an entry is a blank-separated, non-null list of targets, then a :, then a (pos- 
sibly null) list of prerequisite files or dependencies. Text following a ; and all 
following lines that begin with a tab are shell commands to be executed to 
update the target. The first non-empty line that does not begin with a tab or # 
begins a new dependency or macro definition. Shell commands may be con- 
tinued across lines with the < backslash > < new-line > sequence. Everything 
printed by make (except the initial tab) is passed directly to the shell as is. 
Thus, 

echo a\ 
b 

will produce 
ab 

exactly the same as the shell would. 

Sharp (#) and new-line surround comments. 

The following makefile says that pgm depends on two files a.o and b.o, and that 
they in turn depend on their corresponding source files (a.c and b.c) and a 
common file incl.h: 

pgm: a.o b.o 

cc a.o b.o — o pgm 

a. o: incl.h a.c 

cc — c a.c 

b. o: incl.h b.c 

cc — c b.c 

Command lines are executed one at a time, each by its own shell. The SHELL 
environment variable can be used to specify which shell make should use to exe- 
cute commands. The default is / bin/sh . The first one or two characters in a 
command can be the following: — , @, — or @— . If @ is present, printing of 
the command is suppressed. If — is present, make ignores an error. A line is 
printed when it is executed unless the — s option is present, or the entry .SILENT: 
is in makefile , or unless the initial character sequence contains a @. The — n 
option specifies printing without execution; however, if the command line has 
the string $(MAKE) in it, the line is always executed (see discussion of the 
MAKEFLAGS macro under Environment). The — t (touch) option updates the 
modified date of a file without executing any commands. 

Commands returning non-zero status normally terminate make. If the — i option 
is present, or the entry .IGNORE: appears in makefile , or the initial character 
sequence of the command contains — . the error is ignored. If the —k option is 
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present, work is abandoned on the current entry, but continues on other 
branches that do not depend on that entry. 

The —b option allows old makefiles (those written for the old version of make) 
to run without errors. 

Interrupt and quit cause the target to be deleted unless the target is a dependent 
of the special name .PRECIOUS. 

Environment 

The environment is read by make. All variables are assumed to be macro 
definitions and processed as such. The environment variables are processed 
before any makefile and after the internal rules; thus, macro assignments in a 
makefile override environment variables. The — e option causes the environment 
to override the macro assignments in a makefile. Suffixes and their associated 
rules in the makefile will override any identical suffixes in the built-in rules. 

The MAKEFLAGS environment variable is processed by make as containing any 
legal input option (except — f and — p) defined for the command line. Further, 
upon invocation, make "invents" the variable if it is not in the environment, puts 
the current options into it, and passes it on to invocations of commands. Thus, 
MAKEFLAGS always contains the current input options. This proves very useful 
for "super-makes". In fact, as noted above, when the — n option is used, the 
command $(MAKE) is executed anyway; hence, one can perform a make — n 
recursively on a whole software system to see what would have been executed. 
This is because the — n is put in MAKEFLAGS and passed to further invocations 
of $(MAKE). This is one way of debugging all of the makefiles for a software 
project without actually doing anything. 

Include Files 

If the string include appears as the first seven letters of a line in a makefile, and is 
followed by a blank or a tab, the rest of the line is assumed to be a file name 
and will be read by the current invocation, after substituting for any macros. 

Macros 

Entries of the form stringl = string 2 are macro definitions. String 2 is defined as 
all characters up to a comment character or an unescaped new-line. Subsequent 
appearances of $(stringl[:substl=[subst2]]) are replaced by stringl . The 

parentheses are optional if a single character macro name is used and there is no 
substitute sequence. The optional '.substl =subst2 is a substitute sequence. If it is 
specified, all non-overlapping occurrences of substl in the named macro are 
replaced by substl. Strings (for the purposes of this type of substitution) are del- 
imited by blanks, tabs, new-line characters, and beginnings of lines. An 
example of the use of the substitute sequence is shown under Libraries. 

Internal Macros 

There are five internally maintained macros which are useful for writing rules for 
building targets. 

$* The macro $* stands for the file name part of the current dependent with 
the suffix deleted. It is evaluated only for inference rules. 
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$@ The $@ macro stands for the full target name of the current target. It is 
evaluated only for explicitly named dependencies. 

$< The $< macro is only evaluated for inference rules or the .DEFAULT rule. 
It is the module which is out-of-date with respect to the target (i.e., the 
"manufactured" dependent file name). Thus, in the .c.o rule, the $< 
macro would evaluate to the .c file. An example for making optimized .o 
files from .c files is: 

.c.o: 

cc -c -O $*.c 
or: 

.c.o: 

cc -c -O $< 

$? The $? macro is evaluated when explicit rules from the makefile are 
evaluated. It is the list of prerequisites that are out-of-date with respect to 
the target; essentially, those modules which must be rebuilt. 

$% The $% macro is only evaluated when the target is an archive library 
member of the form lib(file.o). In this case, $@ evaluates to lib and $°/o 
evaluates to the library member, file.o. 

Four of the five macros can have alternative forms. When an upper case D or F 
is appended to any of the four macros, the meaning is changed to "directory 
part" for D and "file part" for F. Thus, $(@D) refers to the directory part of the 
string $@. If there is no directory part, ./ is generated. The only macro 
excluded from this alternative form is $?. 

Suffixes 

Certain names (for instance, those ending with . 0 ) have inferable prerequisites 
such as .c, .s, etc. If no update commands for such a file appear in makefile, and 
if an inferable prerequisite exists, that prerequisite is compiled to make the 
target. In this case, make has inference rules which allow building files from 
other files by examining the suffixes and determining an appropriate inference 
rule to use. The current default inference rules are: 

.c .c~ .f .f~ .sh .sh~ 

.c.o .c.a .c~.o .c~.c .c~.a 

.f.o .f.a .f~.o .f~.f .f~.a 

.h~.h .s.o .s~.o .s~.s .s~.a .sh~.sh 

.1.0 .i.e r.o r.i r.c 

.y.o .y.c .y~.o .y~.y .y~.c 

The internal rules for make are contained in the source file rules.c for the make 
program. These rules can be locally modified. To print out the rules compiled 
into the make on any machine in a form suitable for recompilation, the following 
command is used: 

make — fp — 2>/dev/null </dev/null 

A tilde in the above rules refers to an SCCS file [see sccsfile( 4)]. Thus, the rule 
.c~.o would transform an SCCS C source file into an object file (. 0 ). Because the 
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s. of the SCCS files is a prefix, it is incompatible with make's suffix point of view. 
Hence, the tilde is a way of changing any file reference into an SCCS file refer- 
ence. 

A rule with only one suffix (i.e., .c:) is the definition of how to build x from x.c . 
In effect, the other suffix is null. This is useful for building targets from only 
one source file (e.g., shell procedures, simple C programs). 

Additional suffixes are given as the dependency list for .SUFFIXES. Order is 
significant; the first possible name for which both a file and a rule exist is 
inferred as a prerequisite. The default list is: 

.SUFFIXES: .o .c .c~ .y .y~ .1 .1~ .s .s~ .sh .sh~ .h .h~ .f .f~ 

Here again, the above command for printing the internal rules will display the 
list of suffixes implemented on the current machine. Multiple suffix lists accu- 
mulate; .SUFFIXES: with no dependencies clears the list of suffixes. 

Inference Rules 

The first example can be done more briefly. 

pgm: a.o b.o 

cc a.o b.o — o pgm 
a.o b.o: incl.h 

This is because make has a set of internal rules for building files. The user may 
add rules to this list by simply putting them in the makefile. 

Certain macros are used by the default inference rules to permit the inclusion of 
optional matter in any resulting commands. For example, CFLAGS, LFLAGS, and 
YFLAGS are used for compiler options to cc( 1), lex( 1), and yacc( 1), respectively. 
Again, the previous method for examining the current rules is recommended. 

The inference of prerequisites can be controlled. The rule to create a file with 
suffix .o from a file with suffix .c is specified as an entry with .c.o: as the target 
and no dependents. Shell commands associated with the target define the rule 
for making a .o file from a .c file. Any target that has no slashes in it and starts 
with a dot is identified as a rule and not a true target. 

Libraries 

If a target or dependency name contains parentheses, it is assumed to be an 
archive library, the string within parentheses referring to a member within the 
library. Thus lib(file.o) and $(LIB)(file.o) both refer to an archive library which 
contains file.o. (This assumes the LIB macro has been previously defined.) The 
expression $(LIB)(fiIel.o file2.o) is not legal. Rules pertaining to archive libraries 
have the form .XX. a where the XX is the suffix from which the archive member 
is to be made. An unfortunate byproduct of the current implementation requires 
the XX to be different from the suffix of the archive member. Thus, one cannot 
have lib(file.o) depend upon file.o explicitly. The most common use of the 
archive interface follows. Here, we assume the source files are all C type source: 

lib: lib(filel.o) lib(file2.o) lib(file3.o) 

@echo lib is now up-to-date 
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.c.a: 

$(CC) -c $(CFLAGS) $< 

$(AR) $(ARFLAGS) $@ $*.o 
rm — f $*.o 

In fact, the .c.a rule listed above is built into make and is unnecessary in this 
example. A more interesting, but more limited example of an archive library 
maintenance construction follows: 

lib: lib(filel.o) lib(file2.o) lib(file3.o) 

$(CC) -c $(CFLAGS) $(?:.o=.c) 

$(AR) $(ARFLAGS) lib $? 

rm $? @echo lib is now up-to-date 

.c.a:; 

Here the substitution mode of the macro expansions is used. The $? list is 
defined to be the set of object file names (inside lib) whose C source files are 
out-of-date. The substitution mode translates the .o to .c. (Unfortunately, one 
cannot as yet transform to .c~; however, this may become possible in the 
future.) Note also, the disabling of the .c.a: rule, which would have created each 
object file, one by one. This particular construct speeds up archive library 
maintenance considerably. This type of construct becomes very cumbersome if 
the archive library contains a mix of assembly programs and C programs. 

FILES 

[Mmjakefile and s.[Mm]akefile 
/bin/sh 

SEE ALSO 

cc(l), lex(l), yacc(l), printf(3S), sccsfile(4). 
cd(l), sh(l) in the User's Reference Manual 

NOTES 

Some commands return non-zero status inappropriately; use — i to overcome the 
difficulty. 

BUGS 

File names with the characters = : @ will not work. Commands that are directly 
executed by the shell, notably cd( 1), are ineffectual across new-lines in make. 
The syntax (lib(filel.o file2.o file3.o) is illegal. You cannot build lib(file.o) from 
file.o. The macro $(a:.o=.c~) does not work. Named pipes are not handled well. 
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NAME 

mcs — manipulate the object file comment section 
SYNOPSIS 

mcs [options] object-file ... 

DESCRIPTION 

The mcs command manipulates the comment section, normally the ".comment" 
section, in an object file. It is used to add to, delete, print, and compress the 
contents of the comment section in a UNIX System object file, mcs must be 
given one or more of the options described below. It takes each of the options 
given and applies them in order to the object-files. 

If the object file is an archive, the file is treated as a set of individual object files. 
For example, if the —a option is specified, the string is appended to the comment 
section of each archive element. 

The following options are available. 

—a string 

Append string to the comment section of the object-files. If string con- 
tains embedded blanks, it must be enclosed in quotation marks. 

— c Compress the contents of the comment section. All duplicate entries are 

removed. The ordering of the remaining entries is not disturbed. 

— d Delete the contents of the comment section from the object file. The 

object file comment section header is removed also. 

— n name 

Specify the name of the section to access. By default, mcs deals with the 
section named .comment. This option can be used to specify another 
section. 

— p Print the contents of the comment section on the standard output. If 

more than one name is specified, each entry printed is tagged by the 
name of the file from which it was extracted, using the format 
"filename: string/' 

EXAMPLES 

mcs -p file # Print file's comment section. 

mcs -a string file # Append string to file's comment section 

FILES 

TMPDIR/ mcs* temporary files 

TMPDIR/* temporary files 

TMPDIR is usually /usr/tmp but can be redefined by setting the environment 
variable TMPDIR [see tempnamQ in tmpnam( 3S)]. 

SEE ALSO 

cpp(l), a.out(4). 

NOTES 

mcs cannot add new sections or delete existing sections to executable objects 
with magic number 0413 [see a.out( 4)]. 
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NAME 

mkshlib — create a shared library 
SYNOPSIS 

mkshlib — s specfil [— t target] [— h host] [—n] [— q] 

DESCRIPTION 

The mkshlib command builds both the host and target shared libraries. A shared 
library is similar in function to a normal, non-shared library, except that pro- 
grams which link with a shared library will share the library code during execu- 
tion whereas programs which link with a non-shared library will get their own 
copy of each library routine used. 

The host shared library is an archive which is used to link-edit user programs 
with the shared library [see ar( 4)]. A host shared library can be treated exactly 
like a non-shared library and should be included on cc(l) command lines in the 
usual way [see cc(l)]. Further, all operations which can be performed on an 
archive can also be performed on the host shared library. 

The target shared library is an executable module which is attached to the user's 
process during execution of a program using the shared library. The target 
shared library contains the code for all the routines in the library and must be 
fully resolved. The target will be brought into memory during execution of a 
program using the shared library, and subsequent processes which use the 
shared library will share the copy of code already in memory. The text of the 
target is always shared, but each process will get its own copy of the data. 

The user interface to mkshlib consists of command line options and a shared 
library specification file. The shared library specification file describes the con- 
tents of the shared library. 

The mkshlib command invokes other tools such as the archiver, ar{ 1), the assem- 
bler, as( 1), and the loader, ld( 1). Tools are invoked through the use of 
system^ 3S) which searches directories in the user's PATH. Also, prefixes to 
mkshlib are parsed in the same manner as prefixes to the cc( 1) command, and 
invoked tools are given the prefix, where appropriate. For example, 3b2mkshlib 
will invoke 3b2ld. 

The following command line options are recognized by mkshlib: 

— s specfil Specifies the shared library specification file, specfil. This file con- 

tains the information necessary to build a shared library. Its con- 
tents include the branch table specifications for the target, the path- 
name in which the target should be installed, the start addresses of 
text and data for the target, the initialization specifications for the 
host, and the list of object files to be included in the shared library 
(see details below). 

— t target Specifies the name, target, of the target shared library produced on 

the host machine. When target is moved to the target machine, it 
should be installed at the location given in the specification file (see 
the #target directive below). If the — n option is used, then a new 
target shared library will not be generated. 
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— h host Specifies the name of the host shared library, host . If this option is 

not given, then the host shared library will not be produced. 

— n Do not generate a new target shared library. This option is useful 

when producing only a new host shared library. The — t option 
must still be supplied since a version of the target shared library is 
needed to build the host shared library. 

— q Quiet warning messages. This option is useful when warning mes- 

sages are expected but not desired. 

The shared library specification file contains all the information necessary to 
build both the host and target shared libraries. The contents and format of the 
specification file are given by the following directives: 

#address sectname address 

Specifies the start address, address, of section sectname for the 
target. This directive typically is used to specify the start addresses 
of the .text and .data sections. 

#target pathname 

Specifies the absolute pathname, pathname, of the target shared 
library on the target machine. This pathname is copied to a.out 
files and is the location where the operating system will look for 
the shared library when executing a file which uses it. 

#branch 

Specifies the start of the branch table specifications. The lines fol- 
lowing this directive are taken to be branch table specification lines. 

Branch table specification lines have the following format: 

funcname < white space > position 

where funcname is the name of the symbol given a branch table 
entry and position specifies the position of funcname' s branch table 
entry. Position may be a single integer or a range of integers of the 
form positionl-positionl. Each position must be greater than or 
equal to one, the same position can not be specified more than 
once, and every position from one to the highest given position 
must be accounted for. 

If a symbol is given more than one branch table entry by associ- 
ating a range of positions with the symbol or by specifying the 
same symbol on more than one branch table specification line, then 
the symbol is defined to have the address of the highest associated 
branch table entry. All other branch table entries for the symbol 
can be thought of as "empty" slots and can be replaced by new 
entries in future versions of the shared library. 

Finally, only functions should be given branch table entries, and 
those functions must be external. 



79 




MKSHLIB(l) 



(Advanced C Utilities) 



MKSHLIB(l) 



This directive can be specified only once per shared library 

specification file. 

#objects 

Specifies the names of the object files constituting the target shared 
library. The lines following this directive are taken to be the list of 
input object files in the order they are to be loaded into the target. 
The list simply consists of each filename followed by white space. 
This list is also used to determine the input object files for the host 
shared library, but the order for the host is given by running the 
list through lorder( 1) and tsort( 1). 

This directive can be specified only once per shared library 

specification file. 

#init object 

Specifies that the object file, object, requires initialization code. The 
lines following this directive are taken to be initialization 
specification lines. 

Initialization specification lines have the following format: 
pimport < white space > import 

Pimport is a pointer to the associated imported symbol, import , and 
must be defined in the current specified object file, object. The ini- 
tialization code generated for each such line is of the form: 

pimport = &import; 

where pimpaddr is the absolute address of pimport. 

All initializations for a particular object file must be given at once 
and multiple specifications of the same object file are not allowed. 

#ident string 

Specifies a string, string, to be included in the .comment section of 
the target shared library. This directive can be specified only once 
per shared library specification file. 

## 

Specifies a comment. All information on a line following this 
directive is ignored. 

All directives which may be followed by multi-line specifications are valid until 
the next directive or the end of the file. 

FILES 

TEMPDIR/* temporary files 

TEMPDIR is usually /usr/tmp but can be redefined by setting the environment 
variable TMPDIR [see tempnami) in tmpnam( 3S)]. 
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SEE ALSO 

ar(l), as(l), cc(l), ld(l), a.out(4), ar(4). 

Chapter 8 ("Shared Libraries") in the Programmer's Guide. 
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NAME 

nm — print name list of common object file 
SYNOPSIS 

nm [— oxhvnefurpVT] filename ... 

DESCRIPTION 

The nm command displays the symbol table of each common object file, 
filename. Filename may be a relocatable or absolute common object file; or it 
may be an archive of relocatable or absolute common object files. For each 
symbol, the following information will be printed: 

Name The name of the symbol. 

Value Its value expressed as an offset or an address depending on its storage 
class. 

Class Its storage class. 

Type Its type and derived type. If the symbol is an instance of a structure 
or of a union then the structure or union tag will be given following 
the type (e.g., struct-tag). If the symbol is an array, then the array 
dimensions will be given following the type (e.g., char[ n ][ m ] ). 
Note that the object file must have been compiled with the — g option 
of the cc(l) command for this information to appear. 

Size Its size in bytes, if available. Note that the object file must have been 
compiled with the — g option of the cc(l) command for this informa- 
tion to appear. 

Line The source line number at which it is defined, if available. Note that 
the object file must have been compiled with the — g option of the 
cc( 1) command for this information to appear. 

Section For storage classes static and external, the object file section containing 
the symbol (e.g., text, data or bss). 

The output of nm may be controlled using the following options: 

— o Print the value and size of a symbol in octal instead of decimal. 

—x Print the value and size of a symbol in hexadecimal instead of 

decimal. 

—h Do not display the output header data. 

—v Sort external symbols by value before they are printed. 

— n Sort external symbols by name before they are printed. 

— e Print only external and static symbols. 

— f Produce full output. Print redundant symbols (.text, .data, .lib, and 

.bss), normally suppressed. 

— u Print undefined symbols only. 

—r Prepend the name of the object file or archive to each output line. 

“p Produce easily parsable, terse output. Each symbol name is preceded 

by its value (blanks if undefined) and one of the letters U (undefined). 
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A (absolute), T (text segment symbol), D (data segment symbol), S 
(user defined segment symbol), R (register symbol), F (file symbol), or 
C (common symbol). If the symbol is local (non-external), the type 
letter is in lower case. 

—V Print the version of the nm command executing on the standard error 
output. 

— T By default, nm prints the entire name of the symbols listed. Since 

object files can have symbols names with an arbitrary number of char- 
acters, a name that is longer than the width of the column set aside 
for names will overflow its column, forcing every column after the 
name to be misaligned. The — T option causes nm to truncate every 
name which would otherwise overflow its column and place an 
asterisk as the last character in the displayed name to mark it as trun- 
cated. 

Options may be used in any order, either singly or in combination, and may 
appear anywhere in the command line. Therefore, both nm name — e — v and 
nm — ve name print the static and external symbols in name, with external sym- 
bols sorted by value. 

FILES 

TMPD1R/* temporary files 

TMPDIR is usually /usr/tmp but can be redefined by setting the environment 
variable TMPDIR [see tempnamO in tmpnam( 3S)]. 

BUGS 

When all the symbols are printed, they must be printed in the order they appear 
in the symbol table in order to preserve scoping information. Therefore, the — v 
and — n options should be used only in conjunction with the — e option. 

SEE ALSO 

as(l), cc(l), ld(l), tmpnam(3S), a.out(4), ar(4). 

DIAGNOSTICS 

"nm: name: cannot open" 

if name cannot be read. 

"nm: name: bad magic" 

if name is not a common object file. 

"nm: name: no symbols" 

if the symbols have been stripped from name. 
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NAME 

prof — display profile data 
SYNOPSIS 

prof [-tcan] [—ox] [— g] [-z] [— h] [-s] [— m mdata] [prog] 

DESCRIPTION 

The prof command interprets a profile file produced by the monitor( 3C) function. 
The symbol table in the object file prog (a.out by default) is read and correlated 
with a profile file (mon.out by default). For each external text symbol the per- 
centage of time spent executing between the address of that symbol and the 
address of the next is printed, together with the number of times that function 
was called and the average number of milliseconds per call. 

The mutually exclusive options t, c, a, and n determine the type of sorting of 
the output lines: 

— t Sort by decreasing percentage of total time (default). 

— c Sort by decreasing number of calls. 

—a Sort by increasing symbol address. 

— n Sort lexically by symbol name. 

The mutually exclusive options o and x specify the printing of the address of 
each symbol monitored: 

— o Print each symbol address (in octal) along with the symbol name. 

—x Print each symbol address (in hexadecimal) along with the symbol 
name. 

The following options may be used in any combination: 

— g Include non-global symbols (static functions). 

— z Include all symbols in the profile range [see monitor (3C)\, even if associ- 

ated with zero number of calls and zero time. 

— h Suppress the heading normally printed on the report. (This is useful if 

the report is to be processed further.) 

— s Print a summary of several of the monitoring parameters and statistics 

on the standard error output. 

-m mdata 

Use file mdata instead of mon.out as the input profile file. 

A program creates a profile file if it has been loaded with the — p option of cc(l). 
This option to the cc command arranges for calls to monitor( 3C) at the beginning 
and end of execution. It is the call to monitor at the end of execution that causes 
a profile file to be written. The number of calls to a function is tallied if the — p 
option was used when the file containing the function was compiled. 

The name of the file created by a profiled program is controlled by the environ- 
ment variable PROFDIR. If PROFDIR does not exist, "mon.out" is produced in the 
directory that is current when the program terminates. If PROFDIR = string, 
"string/pid.progname" is produced, where progname consists of argv[0] with any 
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path prefix removed, and pid is the program's process id. If PROFDIR is the null 
string, no profiling output is produced. 

A single function may be split into subfunctions for profiling by means of the 
MARK macro [see prof (5)]. 

FILES 

mon.out for profile 
a.out for namelist 

SEE ALSO 

cc(l), exit(2), profil(2), monitor(3C), prof(5). 

WARNING 

The times reported in successive identical runs may show variances of 20% or 
more, because of varying cache-hit ratios due to sharing of the cache with other 
processes. Even if a program seems to be the only one using the machine, 
hidden background or asynchronous processes may blur the data. In rare cases, 
the clock ticks initiating recording of the program counter may "beat" with loops 
in a program, grossly distorting measurements. 

Call counts are always recorded precisely. 

The times for static functions are attributed to the preceding external text symbol 
if the -g option is not used. However, the call counts for the preceding function 
are still correct, i.e., the static function call counts are not added in with the call 
counts of the external function. 

CAVEATS 

Only programs that call exit( 2) or return from main will cause a profile file to be 
produced, unless a final call to monitor is explicitly coded. 

The use of the — p option to cc(l) to invoke profiling imposes a limit of 600 
functions that may have call counters established during program execution. For 
more counters you must call monitor( 3C) directly. If this limit is exceeded, other 
data will be overwritten and the mon.out file will be corrupted. The number of 
call counters used will be reported automatically by the prof command whenever 
the number exceeds 5/6 of the maximum. 
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NAME 

prs - print an SCCS file 
SYNOPSIS 

prs [-d[dataspec]] [-r[SID]] [-e] [-1] [-c[date-time]] [-a] files 
DESCRIPTION 

prs prints, on the standard output, parts or all of an SCCS file [see sccsfile(A)] in a 
user-supplied format. If a directory is named, prs behaves as though each file in 
the directory were specified as a named file, except that non-SCCS files (last 
component of the path name does not begin with s.), and unreadable files are 
silently ignored. If a name of — is given, the standard input is read; each line of 
the standard input is taken to be the name of an SCCS file or directory to be pro- 
cessed; non-SCCS files and unreadable files are silently ignored. 

Arguments to prs, which may appear in any order, consist of keyletter argu- 
ments, and file names. 

All the described keyletter arguments apply independently to each named file: 

—d[dataspec] Used to specify the output data specification. The 
dataspec is a string consisting of SCCS file data keywords 
(see DATA KEYWORDS) interspersed with optional user sup- 
plied text. 

— r [SID] Used to specify the SCCS Identification (SID) string of a 

delta for which information is desired. If no SID is 
specified, the SID of the most recently created delta is 
assumed. 

— e Requests information for all deltas created earlier than and 

including the delta designated via the — r keyletter or the 
date given by the — c option. 

— 1 Requests information for all deltas created later than and 

including the delta designated via the — r keyletter or the 
date given by the — c option. 

c date-time The cutoff date-time — c[cutoff]] is in the form: 
YY[MM[DD[HH[MM[SS]]]]] 

—c [date-time] Units omitted from the date-time default to their max- 
imum possible values; that is, — c7502 is equivalent to 
-C750228235959. Any number of non-numeric characters 
may separate the various 2-digit pieces of the cutoff date 
in the form: "-C77/2/2 9:22:25". 

—a Requests printing of information for both removed, i.e., 

delta type = R, [see rmdel(\)\ and existing, i.e., delta type 
= D, deltas. If the —a keyletter is not specified, informa- 
tion for existing deltas only is provided. 

DATA KEYWORDS 

Data keywords specify which parts of an SCCS file are to be retrieved and 
output. All parts of an SCCS file [see sccsfile(4)] have an associated data 
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keyword. There is no limit on the number of times a data keyword may appear 
in a dataspec. 

The information printed by prs consists of: (1) the user-supplied text; and (2) 
appropriate values (extracted from the SCCS file) substituted for the recognized 
data keywords in the order of appearance in the dataspec. The format of a data 
keyword value is either Simple (S), in which keyword substitution is direct, or 
Multi-line (M), in which keyword substitution is followed by a carriage return. 

User-supplied text is any text other than recognized data keywords. 

A tab is specified by \t and carriage return/new-line is specified by \n. The 
default data keywords are: 

";Dt:\t:DL:\nMRs:\n:MR:COMMENTS:\n:C:" 



TABLE 1. SCCS Files Data Keywords 



Keyword 


Data Item 


File Section 


Value 


Format 


:Dt: 


Delta information 


Delta Table 


See below* 


S 


:DL: 


Delta line statistics 


" 


:Li:/:Ld:/:Lu: 


S 


:Li: 


Lines inserted by Delta 


" 


nnnnn 


s 


:Ld: 


Lines deleted by Delta 


" 


nnnnn 


s 


:Lu: 


Lines unchanged by Delta 


" 


nnnnn 


s 


:DT: 


Delta type 


" 


D~or~R 


s 


si: 


SCCS ID string (SID) 


h 


:R:.:L:.:B:.:S: 


s 


:R: 


Release number 


" 


nnnn 


s 


:L: 


Level number 


it 


nnnn 


s 


:B: 


Branch number 


" 


nnnn 


s 


:S: 


Sequence number 


" 


nnnn 


s 


:D: 


Date Delta created 


•• 


:Dy:/:Dm:/:Dd: 


s 


:Dy: 


Year Delta created 


" 


nn 


s 


:Dm: 


Month Delta created 


" 


nn 


s 


:Dd: 


Day Delta created 


" 


nn 


s 


:T: 


Time Delta created 


" 


:Th:::Tm:::Ts: 


s 


:Th: 


Hour Delta created 


" 


nn 


s 


:Tm: 


Minutes Delta created 


•I 


nn 


s 


:Ts: 


Seconds Delta created 


" 


nn 


s 


:P: 


Programmer who created Delta 


" 


logname 


s 


:DS: 


Delta sequence number 


" 


nnnn 


s 


:DP: 


Predecessor Delta seq-no. 


" 


nnnn 


s 


:DI: 


Seq-no. of deltas incl., excl., ignored 


" 


:Dn:/:Dx:/:Dg: 


s 


:Dn: 


Deltas included (seq #) 


" 


:DS:~:DS:... 


s 


:Dx: 


Deltas excluded (seq #) 


" 


:DS:~:DS:... 


s 


:Dg: 


Deltas ignored (seq #) 




:DS:~:DS:... 


s 


:MR: 


MR numbers for delta 


" 


text 


M 


:C: 


Comments for delta 


" 


text 


M 


:UN: 


User names 


User Names 


text 


M 


:FL: 


Flag list 


Flags 


text 


M 


:Y: 


Module type flag 


" 


text 


S 


:MF: 


MR validation flag 


" 


yes' or~ no 


S 
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Keyword 

:MP: 

:KF: 

:KV: 

:BF: 

:J: 

:LK: 

:Q: 

:M: 

:FB: 

:CB: 

:Ds: 

:ND: 

:FD: 

:BD: 

:GB: 

:W: 

:A: 

:Z: 

:F: 

:PN: 



TABLE 1. SCCS Files Data Keywords (continued) 
Data Item File Section Va 

MR validation pgm name " te 

Keyword error/ warning flag " yes"\ 

Keyword validation string " te 

Branch flag " yes"\ 

Joint edit flag " yes" < 

Locked releases " :R 

User-defined keyword " te 

Module name ” te 

Floor boundary " :] 



Ceiling boundary 
Default SID 



Default SID 
Null delta flag 
File descriptive text 
Body 

Gotten body 
A form of what( 1) string 
A form of what( 1) string 
what( 1) string delimiter 
SCCS file name 
SCCS file path name 

* :D t: ~= ~:DT : ~:I: ~:D : ~:T: ~:P: ~:DS: ~:DP: 



File Section 


Value 


Form 


H 
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H 
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s 


N/A 


:Z::Y:~:M:~:I::2 


:: s 


> N/A 


@(#) 


s 


N/A 


text 


s 


N/A 


text 


s 



EXAMPLES 

prs —d "Users and/or user IDs for :F: are:\n:UN:" s.file 
may produce on the standard output: 

Users and/or user IDs for s.file are: 
xyz 



prs — d"Newest delta for pgm :M:: :I: Created :D: By :P:" — r s.file 
may produce on the standard output: 

Newest delta for pgm main.c: 3.7 Created 77/12/1 By cas 
As a special case: 
prs s.file 

may produce on the standard output: 

D 1.1 77/12/1 00:00:00 cas 1 000000/00000/00000 
MRs: 

bl78-12345 

bl79-54321 

COMMENTS: 

this is the comment line for s.file initial delta 

for each delta table entry of the "D" type. The only keyletter argument allowed 
to be used with the special case is the —a keyletter. 
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FILES 

/tmp/pr????? 

SEE ALSO 

admin(l), delta(l), get(l), sccsfile(4). 
help(l) in the User's Reference Manual. 



DIAGNOSTICS 

Use help( 1) for explanations. 
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NAME 

regcmp — regular expression compile 

SYNOPSIS 

regcmp [ - ] files 

DESCRIPTION 

The regcmp command performs a function similar to regcmp ( 3X) and, in most 
cases, precludes the need for calling regcmp ( 3X) from C programs. This saves on 
both execution time and program size. The command regcmp compiles the reg- 
ular expressions in file and places the output in file. i. If the — option is used, 
the output will be placed in file.c. The format of entries in file is a name (C 
variable) followed by one or more blanks followed by a regular expression 
enclosed in double quotes. The output of regcmp is C source code. Compiled 
regular expressions are represented as extern char vectors. File.i files may thus 
be included in C programs, or file. c files may be compiled and later loaded. In 
the C program which uses the regcmp output, regex(abc,line) will apply the reg- 
ular expression named abc to line. Diagnostics are self-explanatory. 

EXAMPLES 

name ”([A-Za-z][A-Za-z0-9J*)$0" 

telno '\({04)([2— 91[01][1— 9])$0\){0,l) *" 

"([2— 9][0— 9]{2})$1[ -){0,1}" 

"([0— 9]{4})$2" 

In the C program that uses the regcmp output, 
regex(telno, line, area, exch, rest) 
will apply the regular expression named telno to line. 

SEE ALSO 

regcmp(3X). 
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NAME 

relogin — rename login entry to show current layer 
SYNOPSIS 

/usr/lib/layersys/relogin [— s] [line] 

DESCRIPTION 

The relogin command changes the terminal line field of a user's utmp( 4) entry to 
the name of the windowing terminal layer attached to standard input. write( 1) 
messages sent to this user are directed to this layer. In addition, the who( 1) 
command will show the user associated with this layer, relogin may only be 
invoked under layers( 1). 

relogin is invoked automatically by layers( 1) to set the utmp( 4) entry to the ter- 
minal line of the first layer created upon startup, and to reset the utmp( 4) entry 
to the real line on termination. It may be invoked by a user to designate a 
different layer to receive write( 1) messages. 

— s Suppress error messages. 

line Specifies which utmp( 4) entry to change. The utmp(4i) file is searched 
for an entry with the specified line field. That field is changed to the 
line associated with the standard input. (To learn what lines are associ- 
ated with a given user, say jdoe, type ps -f -u jdoe and note the values 
shown in the TTY field (see ps( 1))). 

FILES 

/etc/utmp database of users versus terminals 
EXIT STATUS 

Returns 0 upon successful completion, 1 otherwise. 

SEE ALSO 

utmp(4) in the Programmer's Reference Manual . 

layers(l), mesg(l), ps(l), who(l), write(l) in the User's Reference Manual. 

NOTES 

If line does not belong to the user issuing the relogin command or standard input 
is not associated with a terminal, relogin will fail. 
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NAME 

rmdel — remove a delta from an SCCS file 

SYNOPSIS 

rmdel — rSID files 

DESCRIPTION 

rmdel removes the delta specified by the SID from each named SCCS file. The 
delta to be removed must be the newest (most recent) delta in its branch in the 
delta chain of each named SCCS file. In addition, the specified must not be that 
of a version being edited for the purpose of making a delta (i. e., if a p-file [see 
get( 1)] exists for the named SCCS file, the specified must not appear in any entry 
of the p-file ). 

The — r option is used for specifying the SID (SCCS IDentification) level of the 
delta to be removed. 

If a directory is named, rmdel behaves as though each file in the directory were 
specified as a named file, except that non-SCCS files (last component of the path 
name does not begin with s.) and unreadable files are silently ignored. If a 
name of — is given, the standard input is read; each line of the standard input is 
taken to be the name of an SCCS file to be processed; non-SCCS files and 
unreadable files are silently ignored. 

Simply stated, they are either (1) if you make a delta you can remove it; or (2) if 
you own the file and directory you can remove a delta. 

FILES 

x.file [see delta( 1)] 

z.file [see delta( 1)] 

SEE ALSO 

delta(l), get(l), prs(l), sccsfile(4). 
help(l) in the User's Reference Manual. 

DIAGNOSTICS 

Use help( 1) for explanations. 
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NAME 

sact — print current SCCS file editing activity 

SYNOPSIS 

sact files 

DESCRIPTION 

sact informs the user of any impending deltas to a named SCCS file. This situa- 
tion occurs when get( 1) with the — e option has been previously executed 
without a subsequent execution of delta( 1). If a directory is named on the com- 
mand line, sact behaves as though each file in the directory were specified as a 
named file, except that non-SCCS files and unreadable files are silently ignored. 
If a name of — is given, the standard input is read with each line being taken as 
the name of an SCCS file to be processed. 

The output for each named file consists of five fields separated by spaces. 

Field 1 specifies the SID of a delta that currently exists in the SCCS 

file to which changes will be made to make the new delta. 

Field 2 specifies the SID for the new delta to be created. 

Field 3 contains the logname of the user who will make the delta 
(i.e., executed a get for editing). 

Field 4 contains the date that get — e was executed. 

Field 5 contains the time that get — e was executed. 

SEE ALSO 

delta(l), get(l), unget(l). 

DIAGNOSTICS 

Use help( 1) for explanations. 
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NAME 

sccsdiff — compare two versions of an SCCS file 
SYNOPSIS 

sccsdiff -rSIDl -rSID2 [-p] [-sn] files 
DESCRIPTION 

sccsdiff compares two versions of an SCCS file and generates the differences 
between the two versions. Any number of SCCS files may be specified, but 
arguments apply to all files. 

— r SID? SID1 and SID2 specify the deltas of an SCCS file that are to be 

compared. Versions are passed to bdiff( 1) in the order given. 

— p pipe output for each file through pr( 1). 

— sn n is the file segment size that bdiff will pass to diff( 1). This is 

useful when diff fails due to a high system load. 



FILES 

/tmp/get????? Temporary files 



SEE ALSO 

get(l). 

bdiff(l), help(l), pr(l) in the User's Reference Manual. 



DIAGNOSTICS 

"file: No differences" If the two versions are the same. 
Use help( 1) for explanations. 
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NAME 

sdb — symbolic debugger 
SYNOPSIS 

sdb [— ■ w] [— W] [objfil [corfil [directory-list]]] 

DESCRIPTION 

The sdb command calls a symbolic debugger that can be used with C and F 77 
programs. It may be used to examine their object files and core files and to pro- 
vide a controlled environment for their execution. 

Objfil is an executable program file which has been compiled with the — g 
(debug) option. If it has not been compiled with the — g option the symbolic 
capabilities of sdb will be limited, but the file can still be examined and the pro- 
gram debugged. The default for objfil is a.out. Corfil is assumed to be a core 
image file produced after executing objfil ; the default for corfil is core. The core 
file need not be present. A — in place of corfil will force sdb to ignore any core 
image file. The colon separated list of directories (dire dory -list) is used to locate 
the source files used to build objfil. 

It is useful to know that at any time there is a current line and current file. If 
corfil exists then they are initially set to the line and file containing the source 
statement at which the process terminated. Otherwise, they are set to the first 
line in mainQ. The current line and file may be changed with the source file 
examination commands. 

By default, warnings are provided if the source files used in producing objfil 
cannot be found, or are newer than objfil. This checking feature and the accom- 
panying warnings may be disabled by the use of the — W flag. 

Names of variables are written just as they are in C or F 77. sdb does not trun- 
cate names. Variables local to a procedure may be accessed using the form pro- 
cedure ivariable. If no procedure name is given, the procedure containing the 
current line is used by default. 

It is also possible to refer to structure members as variable, member, pointers to 
structure members as variable— > member and array elements as variable[number]. 
Pointers may be dereferenced by using the form pointer[ 0]. Combinations of 
these forms may also be used. F 77 common variables may be referenced by 
using the name of the common block instead of the structure name. Blank 
common variables may be named by the form . variable . A number may be used 
in place of a structure variable name, in which case the number is viewed as the 
address of the structure, and the template used for the structure is that of the 
last structure referenced by sdb. An unqualified structure variable may also be 
used with various commands. Generally, sdb will interpret a structure as a set of 
variables. Thus, sdb will display the values of all the elements of a structure 
when it is requested to display a structure. An exception to this interpretation 
occurs when displaying variable addresses. An entire structure does have an 
address, and it is this value sdb displays, not the addresses of individual ele- 
ments. 

Elements of a multidimensional array may be referenced as variable 
[number] [number]..., or as variable [number, number,...]. In place of number, the 
form number;number may be used to indicate a range of values, * may be used to 
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indicate all legitimate values for that subscript, or subscripts may be omitted 
entirely if they are the last subscripts and the full range of values is desired. As 
with structures, sdb displays all the values of an array or of the section of an 
array if trailing subscripts are omitted. It displays only the address of the array 
itself or of the section specified by the user if subscripts are omitted. A multidi- 
mensional parameter in an F 77 program cannot be displayed as an array, but it 
is actually a pointer, whose value is the location of the array. The array itself 
can be accessed symbolically from the calling function. 

A particular instance of a variable on the stack may be referenced by using the 
form procedures ariable, number. All the variations mentioned in naming vari- 
ables may be used. Number is the occurrence of the specified procedure on the 
stack, counting the top, or most current, as the first. If no procedure is specified, 
the procedure currently executing is used by default. 

It is also possible to specify a variable by its address. All forms of integer con- 
stants which are valid in C may be used, so that addresses may be input in 
decimal, octal or hexadecimal. 

Line numbers in the source program are referred to as file -name inumber or pro- 
cedure inumber. In either case the number is relative to the beginning of the file. 
If no procedure or file name is given, the current file is used by default. If no 
number is given, the first line of the named procedure or file is used. 

While a process is running under sdb, all addresses refer to the executing pro- 
gram; otherwise they refer to objfil or corfil. An initial argument of — w permits 
overwriting locations in objfil. 

Addresses 

The address in a file associated with a written address is determined by a map- 
ping associated with that file. Each mapping is represented by two triples (bl, 
el, fl) and (b2, e2 , /2) and the file address corresponding to a written address is 
calculated as follows: 

bl <=address<el 

file address=address+fl-bl 
otherwise 

b2<=address<e2 

file address=address+f2—b2, 

otherwise, the requested address is not legal. In some cases (e.g., for programs 
with separated I and D space) the two segments for a file may overlap. 

The initial setting of both mappings is suitable for normal a.out and core files. 
If either file is not of the kind expected then, for that file, 272 is set to 0, el is set 
to the maximum file size, and fl is set to 0; in this way the whole file can be 
examined with no address translation. 

In order for sdb to be used on large files, all appropriate values are kept as 
signed 3 2 -bit integers. 
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Commands 

The commands for examining data in the program are: 
t Print a stack trace of the terminated or halted program. 

T Print the top line of the stack trace. 
variable / dm 

Print the value of variable according to length l and format m. A numeric 
count c indicates that a region of memory, beginning at the address 
implied by variable, is to be displayed. The length specifiers are: 
b one byte 

h two bytes (half word) 

1 four bytes (long word) 

Legal values for m are: 

c character 

d decimal 

u decimal, unsigned 

0 octal 

x hexadecimal 

f 3 2 -bit single precision floating point 

g 64-bit double precision floating point 

s Assume variable is a string pointer and print characters 

starting at the address pointed to by the variable, 
a Print characters starting at the variable's address. This 
format may not be used with register variables, 
p pointer to procedure 

1 disassemble machine-language instruction with addresses 
printed numerically and symbolically. 

I disassemble machine-language instruction with addresses 

just printed numerically. 

Length specifiers are only effective with the c, d, u, o and x formats. Any 
of the specifiers, c, l, and m, may be omitted. If all are omitted, sdb 
chooses a length and a format suitable for the variable's type as declared in 
the program. If m is specified, then this format is used for displaying the 
variable. A length specifier determines the output length of the value to be 
displayed, sometimes resulting in truncation. A count specifier c tells sdb 
to display that many units of memory, beginning at the address of variable. 
The number of bytes in one such unit of memory is determined by the 
length specifier Z, or if no length is given, by the size associated with the 
variable. If a count specifier is used for the s or a command, then that 
many characters are printed. Otherwise successive characters are printed 
until either a null byte is reached or 128 characters are printed. The last 
variable may be redisplayed with the command ./. 

The sh( 1) metacharacters * and ? may be used within procedure and vari- 
able names, providing a limited form of pattern matching. If no procedure 
name is given, variables local to the current procedure and global variables 
are matched; if a procedure name is specified then only variables local to 
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that procedure are matched. To match only global variables, the form '.pat- 
tern is used. 

linenumberllm 

variable:?lm 

Print the value at the address from a.out or I space given by linenumber or 
variable (procedure name), according to the format Im. The default format 
is Y. 

variable=lm 

linenumber=lm 

number=lm 

Print the address of variable or linenumber , or the value of number, in the 
format specified by Im. If no format is given, then lx is used. The last 
variant of this command provides a convenient way to convert between 
decimal, octal and hexadecimal. 

variablelvalue 

Set variable to the given value. The value may be a number, a character 
constant or a variable. The value must be well defined; expressions which 
produce more than one value, such as structures, are not allowed. Char- 
acter constants are denoted ' character . Numbers are viewed as integers 
unless a decimal point or exponent is used. In this case, they are treated 
as having the type double. Registers are viewed as integers. The variable 
may be an expression which indicates more than one variable, such as an 
array or structure name. If the address of a variable is given, it is regarded 
as the address of a variable of type int. C conventions are used in any 
type conversions necessary to perform the indicated assignment. 

x Print the machine registers and the current machine-language instruction. 

X Print the current machine-language instruction. 

The commands for examining source files are: 

e procedure 
e file-name 
e directory/ 
e directory file-name 

The first two forms set the current file to the file containing procedure or to 
file-name. The current line is set to the first line in the named procedure or 
file. Source files are assumed to be in directory. The default is the current 
working directory. The latter two forms change the value of directory. If 
no procedure, file name, or directory is given, the current procedure name 
and file name are reported. 

/regular expression / 

Search forward from the current line for a line containing a string matching 
regular expression as in ed(l). The trailing / may be deleted. 

Iregular expression? 

Search backward from the current line for a line containing a string 
matching regular expression as in ed( 1). The trailing ? may be deleted. 
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p Print the current line. 

z Print the current line followed by the next 9 lines. Set the current line to 
the last line printed. 

w Window. Print the 10 lines around the current line. 
number 

Set the current line to the given line number. Print the new current line. 
counts 

Advance the current line by count lines. Print the new current line. 
count— 

Retreat the current line by count lines. Print the new current line. 

The commands for controlling the execution of the source program are: 

count r args 
count R 

Run the program with the given arguments. The r command with no 
arguments reuses the previous arguments to the program while the R com- 
mand runs the program with no arguments. An argument beginning with 
< or > causes redirection for the standard input or output, respectively. If 
count is given, it specifies the number of breakpoints to be ignored. 

linenumber c count 
linenumber C count 

Continue after a breakpoint or interrupt. If count is given, the program 
will stop when count breakpoints have been encountered. The signal 
which caused the program to stop is reactivated with the C command and 
ignored with the c command. If a line number is specified then a tem- 
porary breakpoint is placed at the line and execution is continued. The 
breakpoint is deleted when the command finishes. 

linenumber g count 

Continue after a breakpoint with execution resumed at the given line. If 
count is given, it specifies the number of breakpoints to be ignored. 

s count 
S count 

Single step the program through count lines. If no count is given then the 
program is run for one line. S is equivalent to s except it steps through 
procedure calls. 

i 

I Single step by one machine-language instruction. The signal which caused 
the program to stop is reactivated with the I command and ignored with 
the i command. 

variable $ m count 
address : m count 

Single step (as with s) until the specified location is modified with a new 
value. If count is omitted, it is effectively infinity. Variable must be acces- 
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sible from the current procedure. Since this command is done by software, 
it can be very slow. 

level v 

Toggle verbose mode, for use when single stepping with S, s or m. If level 
is omitted, then just the current source file and/or subroutine name is 
printed when either changes. If level is 1 or greater, each C source line is 
printed before it is executed; if level is 2 or greater, each assembler state- 
ment is also printed. A v turns verbose mode off if it is on for any level. 

k Kill the program being debugged. 

procedure(argl ,arg2, . . .) 
procedure(argl ,arg2, . . .)/m 

Execute the named procedure with the given arguments. Arguments can 
be integer, character or string constants or names of variables accessible 
from the current procedure. The second form causes the value returned by 
the procedure to be printed according to format m. If no format is given, it 
defaults to d. This facility is only available if the program was loaded with 
the — g option. 

linenumber b commands 

Set a breakpoint at the given line. If a procedure name without a line 
number is given (e.g., "proc:"), a breakpoint is placed at the first line in the 
procedure even if it was not compiled with the — g option. If no 
linenumber is given, a breakpoint is placed at the current line. If no com- 
mands are given, execution stops just before the breakpoint and control is 
returned to sdb. Otherwise the commands are executed when the break- 
point is encountered and execution continues. Multiple commands are 
specified by separating them with semicolons. If k is used as a command 
to execute at a breakpoint, control returns to sdb, instead of continuing exe- 
cution. 

B Print a list of the currently active breakpoints. 
linenumber d 

Delete a breakpoint at the given line. If no linenumber is given then the 
breakpoints are deleted interactively. Each breakpoint location is printed 
and a line is read from the standard input. If the line begins with a y or d 
then the breakpoint is deleted. 

D Delete all breakpoints. 

1 Print the last executed line. 

linenumber a 

Announce. If linenumber is of the form procmumber, the command 
effectively does a linenumber b 1. If linenumber is of the form proc:, the 
command effectively does a proc: b T. 

Miscellaneous commands: 

! command 

The command is interpreted by sh(l). 
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new-line 

If the previous command printed a source line, then advance the current 
line by one line and print the new current line. If the previous command 
displayed a memory location, then display the next memory location. 

end-of-file character 

Scroll. Print the next 10 lines of instructions, source or data depending on 
which was printed last. The end-of-file character is usually control-D. 

< filename 

Read commands from filename until the end of file is reached, and then 
continue to accept commands from standard input. When sdb is told to 
display a variable by a command in such a file, the variable name is 
displayed along with the value. This command may not be nested; < may 
not appear as a command in a file. 

M Print the address maps. 

M [?/] [*]bef 

Record new values for the address map. The arguments ? and / specify 
the text and data maps, respectively. The first segment (bl, el, fl) is 
changed unless * is specified, in which case the second segment ( b2 , e2, f2) 
of the mapping is changed. If fewer than three values are given, the 
remaining map parameters are left unchanged. 

" string 

Print the given string. The C escape sequences of the form \character are 
recognized, where character is a nonnumeric character. 

q Exit the debugger. 

The following commands also exist and are intended only for debugging the 
debugger: 

V Print the version number. 

Q Print a list of procedures and files being debugged. 

Y Toggle debug output. 

FILES 

a.out 

core 

SEE ALSO 

cc(l), a.out(4), core(4), syms(4). 
sh(l) in the User's Reference Manual. 

177(1) in the FORTRAN Programming Language Manual. 

WARNINGS 

When sdb prints the value of an external variable for which there is no debug- 
ging information, a warning is printed before the value. The size is assumed to 
be int (integer). 

Data which are stored in text sections are indistinguishable from functions. 

Line number information in optimized functions is unreliable, and some infor- 
mation may be missing. 
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BUGS 

If a procedure is called when the program is not stopped at a breakpoint (such 
as when a core image is being debugged), all variables are initialized before the 
procedure is started. This makes it impossible to use a procedure which formats 
data from a core image. 

sdb cannot print the value of an F 77 parameter. It will erroneously print the 
address. 

Tracebacks containing F 77 subprograms with multiple entry points may print too 
many arguments in the wrong order, but their values are correct. 

The range of an F 77 array subscript is assumed to be 1 to n, where n is the 
dimension corresponding to that subscript. This is only significant when the 
user omits a subscript, or uses * to indicate the full range. There is no problem 
in general with arrays having subscripts whose lower bounds are not 1. 
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NAME 

size — print section sizes in bytes of common object files 
SYNOPSIS 

size [— n] [— f] [-o] [-x] [-V] files 
DESCRIPTION 

The size command produces section size information in bytes for each loaded 
section in the common object files. The size of the text, data, and bss (uninitial- 
ized data) sections is printed, as well as the sum of the sizes of these sections. If 
an archive file is input to the size command the information for all archive 
members is displayed. 

The -n option includes NOLOAD sections in the size. 

The -f option produces full output, that is, it prints the size of every loaded sec- 
tion, followed by the section name in parentheses. 

Numbers will be printed in decimal unless either the — o or the — x option is 
used, in which case they will be printed in octal or in hexadecimal, respectively. 

The — V flag will supply the version information on the size command. 

SEE ALSO 

as(l), cc(l), ld(l), a.out(4), ar(4). 

CAVEAT 

Since the size of bss sections is not known until link-edit time, the size com- 
mand will not give the true total size of pre-linked objects. 

DIAGNOSTICS 

size: name: cannot open 

if name cannot be read. 

size: name: bad magic 

if name is not an appropriate common object file. 
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NAME 

strip — strip symbol and line number information from a common object file 
SYNOPSIS 

strip [-1] [— x] [-b] [-r] [— V] filename ... 

DESCRIPTION 

The strip command strips the symbol table and line number information from 
common object files, including archives. Once this has been done, no symbolic 
debugging access will be available for that file; therefore, this command is nor- 
mally run only on production modules that have been debugged and tested. 

The amount of information stripped from the symbol table can be controlled by 
using any of the following options: 

—1 Strip line number information only; do not strip any symbol table 

information. 

—x Do not strip static or external symbol information. 

— b Same as the — x option, but also do not strip scoping information (e.g., 

beginning and end of block delimiters). 

— r Do not strip static or external symbol information, or relocation infor- 

mation. 

—V Print the version of the strip command executing on the standard error 
output. 

If there are any relocation entries in the object file and any symbol table infor- 
mation is to be stripped, strip will complain and terminate without stripping 
filename unless the — r option is used. 

If the strip command is executed on a common archive file [see ar( 4)] the archive 
symbol table will be removed. The archive symbol table must be restored by 
executing the ar( 1) command with the s option before the archive can be link- 
edited by the ld( 1) command, strip will produce appropriate warning messages 
when this situation arises. 

strip is used to reduce the file storage overhead taken by the object file. 

FILES 

TMPDIR/ strp* temporary files 

TMPDIR is usually /usr/tmp but can be redefined by setting the environment 
variable TMPDIR [see tempnamQ in tmpnam( 3S)]. 

SEE ALSO 

ar(l), as(l), cc(l), ld(l), tmpnam(3S), a.out(4), ar(4). 

DIAGNOSTICS 

strip: name: cannot open 

if name cannot be read. 

strip: name: bad magic 

if name is not an appropriate common object file. 
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strip: name: relocation entries present; cannot strip 

if name contains relocation entries and the — r flag 
is not used, the symbol table information 
cannot be stripped. 
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NAME 

tic — terminfo compiler 

SYNOPSIS 

tic [— v[n]] [— c] file 

DESCRIPTION 

tic translates a terminfo( 4) file from the source format into the compiled format. 
The results are placed in the directory /usr/ lib /terminfo. The compiled format is 
necessary for use with the library routines described in curses( 3X). 

— vn (verbose) output to standard error trace information showing tic's pro- 

gress. The optional integer n is a number from 1 to 10, inclusive, indi- 
cating the desired level of detail of information. If n is omitted, the 
default level is 1. If n is specified and greater than 1, the level of detail 
is increased. 

— c only check file for errors. Errors in use= links are not detected. 

file contains one or more terminfo( 4) terminal descriptions in source format 
(see terminfo( 4)). Each description in the file describes the capabilities 
of a particular terminal. When a use** entry -name field is discovered in 
a terminal entry currently being compiled, tic reads in the binary from 
/usr /lib /terminfo to complete the entry. (Entries created from file will 
be used first. If the environment variable TERMINFO is set, that direc- 
tory is searched instead of /usr /lib /terminfo.) tic duplicates the capabili- 
ties in entry-name for the current entry, with the exception of those 
capabilities that explicitly are defined in the current entry. 

If the environment variable TERMINFO is set, the compiled results are placed 
there instead of /usr /lib /terminfo. 

FILES 

/usr /lib /terminfo/?/* compiled terminal description data base 

SEE ALSO 

curses(3X), term(4), terminfo(4) in the Programmer's Reference Manual. 

Chapter 10 in the Programmer's Guide. 

WARNINGS 

Total compiled entries cannot exceed 4096 bytes. The name field cannot exceed 
128 bytes. 

Terminal names exceeding 14 characters will be truncated to 14 characters and a 
warning message will be printed. 

When the — c option is used, duplicate terminal names will not be diagnosed; 
however, when — c is not used, they will be. 

BUGS 

To allow existing executables from the previous release of the UNIX System to 
continue to run with the compiled terminfo entries created by the new terminfo 
compiler, cancelled capabilities will not be marked as cancelled within the ter- 
minfo binary unless the entry name has a '+' within it. (Such terminal names 
are only used for inclusion within other entries via a use= entry. Such names 
would not be used for real terminal names.) 
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For example: 

4415+nl, kfl@, kf2@, .... 

4415+base, kfl=\EOc, kf2=\EOd, .... 

4415-nl|4415 terminal without keys, 
use=4415+nl, use=4415+base. 

The above example works as expected; the definitions for the keys do not show 
up in the 4425 — nl entry. However, if the entry 4415+nl did not have a plus sign 
within its name, the cancellations would not be marked within the compiled file 
and the definitions for the function keys would not be cancelled within 4415— nl. 

DIAGNOSTICS 

Most diagnostic messages produced by tic during the compilation of the source 
file are preceded with the approximate line number and the name of the ter- 
minal currently being worked on. 

mkdir ... returned bad status 

The named directory could not be created. 

File does not start with terminal names in column one 

The first thing seen in the file, after comments, must be the list of ter- 
minal names. 

Token after a seek( 2) not NAMES 

Somehow the file being compiled changed during the compilation. 

Not enough memory for usejist element 
or 

Out of memory 

Not enough free memory was available (malloc( 3) failed). 

Can't open ... 

The named file could not be created. 

Error in writing ... 

The named file could not be written to. 

Can't link ... to ... 

A link failed. 

Error in re-reading compiled file ... 

The compiled file could not be read back in. 

Premature EOF 

The current entry ended prematurely. 

Backspaced off beginning of line 

This error indicates something wrong happened within tic. 

Unknown Capability - ”..." 

The named invalid capability was found within the file. 

Wrong type used for capability "..." 

For example, a string capability was given a numeric value. 
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Unknown token type 

Tokens must be followed by '(a)' to cancel, '/ for booleans, '#' for 
numbers, or '=' for strings. 

bad term name 
or 

Line Illegal terminal name - 

Terminal names must start with a letter or digit 

The given name was invalid. Names must not contain white space or 
slashes, and must begin with a letter or digit. 

terminal name too long. 

An extremely long terminal name was found. 

terminal name too short. 

A one-letter name was found. 

"..." filename too long, truncating to "..." 

The given name was truncated to 14 characters due to UNIX file name 
length limitations. 

"..." defined in more than one entry. Entry being used is 
An entry was found more than once. 

Terminal name "..." synonym for itself 

A name was listed twice in the list of synonyms. 

At least one synonym should begin with a letter. 

At least one of the names of the terminal should begin with a letter. 

Illegal character - "...” 

The given invalid character was found in the input file. 

Newline in middle of terminal name 

The trailing comma was probably left off of the list of names. 

Missing comma 

A comma was missing. 

Missing numeric value 

The number was missing after a numeric capability. 

NULL string value 

The proper way to say that a string capability does not exist is to cancel 

it 

Very long string found. Missing comma? 
self-explanatory 

Unknown option. Usage is: 

An invalid option was entered. 

Too many file names. Usage is: 
self-explanatory 

"..." non-existant or permission denied 

The given directory could not be written into. 
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"..." is not a directory 

self-explanatory 

Permission denied 
access denied. 

Not a directory 

tic wanted to use the given name as a directory, but it already exists as 
a file 

SYSTEM ERROR!! Fork failed!!! 

A fork( 2) failed. 

Error in following up use-links. Either there is a loop in the links or they refer- 
ence non-existant terminals. The following is a list of the entries involved: 

A terminfo( 4) entry with a username capability either referenced a non- 
existant terminal called name or name somehow referred back to the 
given entry. 
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NAME 

tsort — topological sort 

SYNOPSIS 

tsort [file] 

DESCRIPTION 

The tsort command produces on the standard output a totally ordered list of 
items consistent with a partial ordering of items mentioned in the input file. If 
no file is specified, the standard input is understood. 

The input consists of pairs of items (nonempty strings) separated by blanks. 
Pairs of different items indicate ordering. Pairs of identical items indicate pres- 
ence, but not ordering. 

SEE ALSO 

lorder(l). 

DIAGNOSTICS 

Odd data: there is an odd number of fields in the input file. 
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NAME 

unget — undo a previous get of an SCCS file 
SYNOPSIS 

unget [— rSID] [— s] [— n] files 
DESCRIPTION 

unget undoes the effect of a get — e done prior to creating the intended new 
delta. If a directory is named, unget behaves as though each file in the directory 
were specified as a named file, except that non-SCCS files and unreadable files 
are silently ignored. If a name of — is given, the standard input is read with 
each line being taken as the name of an SCCS file to be processed. 

Keyletter arguments apply independently to each named file. 

— r SID Uniquely identifies which delta is no longer intended. (This 

would have been specified by get as the "new delta"). The 
use of this keyletter is necessary only if two or more out- 
standing gets for editing on the same SCCS file were done by 
the same person (login name). A diagnostic results if the 
specified SID is ambiguous, or if it is necessary and omitted 
on the command line. 

— s Suppresses the printout, on the standard output, of the 

intended delta's SID. 

— n Causes the retention of the gotten file which would normally 

be removed from the current directory. 

SEE ALSO 

delta(l), get(l), sact(l). 

help(l) in the User's Reference Manual. 

DIAGNOSTICS 

Use help( 1) for explanations. 
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NAME 

val — validate SCCS file 

SYNOPSIS 

val — 

val [— s] [—rSID] [— mname] [—ytype] files 
DESCRIPTION 

val determines if the specified file is an SCCS file meeting the characteristics 
specified by the optional argument list. Arguments to val may appear in any 
order. The arguments consist of keyletter arguments, which begin with a — , and 
named files. 

val has a special argument, — , which causes reading of the standard input until 
an end-of-file condition is detected. Each line read is independently processed 
as if it were a command line argument list. 

val generates diagnostic messages on the standard output for each command line 
and file processed, and also returns a single 8-bit code upon exit as described 
below. 

The keyletter arguments are defined as follows. The effects of any keyletter 
argument apply independently to each named file on the command line. 

— s The presence of this argument silences the diagnostic message nor- 

mally generated on the standard output for any error that is 
detected while processing each named file on a given command 
line. 

—rSID The argument value SID (SCCS IDe ntification String) is an SCCS 

delta number. A check is made to determine if the SID is ambi- 
guous (e. g., rl is ambiguous because it physically does not exist 
but implies 1.1, 1.2, etc., which may exist) or invalid (e. g., rl.O or 
r 1.1.0 are invalid because neither case can exist as a valid delta 
number). If the SID is valid and not ambiguous, a check is made to 
determine if it actually exists. 

—mname The argument value name is compared with the s-lSCCS %M% 
keyword in file. 

— ytype The argument value type is compared with the SCCS %Y% key- 

word in file. 

The 8-bit code returned by val is a disjunction of the possible errors, i. e., can be 
interpreted as a bit string where (moving from left to right) set bits are inter- 
preted as follows: 

bit 0 — missing file argument; 

bit 1 = unknown or duplicate keyletter argument; 

bit 2 = corrupted SCCS file; 

bit 3 = cannot open file or file not SCCS; 

bit 4 = SID is invalid or ambiguous; 

bit 5 = SID does not exist; 

bit 6 = %Y%, — y mismatch; 

bit 7 = %M%, — m mismatch; 
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Note that val can process two or more files on a given command line and in 
turn can process multiple command lines (when reading the standard input). In 
these cases an aggregate code is returned — a logical OR of the codes generated 
for each command line and file processed. 

SEE ALSO 

admin(l), delta(l), get(l), prs(l). 
help(l) in the User's Reference Manual. 

DIAGNOSTICS 

Use help( 1) for explanations. 



BUGS 



val can process up to 50 files on a single command line. Any number above 50 
will produce a core dump. 
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NAME 

vc — version control 
SYNOPSIS 

vc [“ a ] [ — t] [— cchar] [— s] [keyword=value ... keyword=value] 

DESCRIPTION 

The vc command copies lines from the standard input to the standard output 
under control of its arguments and control statements encountered in the standard 
input. In the process of performing the copy operation, user declared keywords 
may be replaced by their string value when they appear in plain text and/or 
control statements. 

The copying of lines from the standard input to the standard output is condi- 
tional, based on tests (in control statements) of keyword values specified in con- 
trol statements or as vc command arguments. 

A control statement is a single line beginning with a control character, except as 
modified by the — t keyletter (see below). The default control character is colon 
(:), except as modified by the — c keyletter (see below). Input lines beginning 
with a backslash (\) followed by a control character are not control lines and are 
copied to the standard output with the backslash removed. Lines beginning 
with a backslash followed by a non-control character are copied in their entirety. 

A keyword is composed of 9 or less alphanumerics; the first must be alphabetic. 
A value is any ASCII string that can be created with ed( 1); a numeric value is an 
unsigned string of digits. Keyword values may not contain blanks or tabs. 

Replacement of keywords by values is done whenever a keyword surrounded by 
control characters is encountered on a version control statement. The —a 
keyletter (see below) forces replacement of keywords in all lines of text. An 
uninterpreted control character may be included in a value by preceding it with 
\. If a literal \ is desired, then it too must be preceded by \. 

Keyletter Arguments 

—a Forces replacement of keywords surrounded by control characters 

with their assigned value in all text lines and not just in vc state- 
ments. 

— t All characters from the beginning of a line up to and including the 

first tab character are ignored for the purpose of detecting a control 
statement. If one is found, all characters up to and including the 
tab are discarded. 

—cchar Specifies a control character to be used in place of :. 

— s Silences warning messages (not error) that are normally printed on 

the diagnostic output. 

Version Control Statements 

:dcl keyword[, ..., keyword] 

Used to declare keywords. All keywords must be declared. 
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:asg keyword=value 

Used to assign values to keywords. An asg statement overrides the assign- 
ment for the corresponding keyword on the vc command line and all pre- 
vious asg's for that keyword. Keywords declared, but not assigned values 
have null values. 

:if condition 



:end 

Used to skip lines of the standard input. If the condition is true all lines 
between the if statement and the matching end statement are copied to the 
standard output. If the condition is false, all intervening lines are dis- 
carded, including control statements. Note that intervening if statements 
and matching end statements are recognized solely for the purpose of 
maintaining the proper if-end matching. 

The syntax of a condition is: 

= [ "not" ] <or> 

= <and> I <and> T <or> 

= <exp> I <exp> <and> 

= "(" <or> ")" I < value > <op> < value > 

_ II tl | llj_tl | II ^ II | II > It 

= < arbitrary ASCII string > I < numeric string > 

The available operators and their meanings are: 



<cond> 

<or> 

<and> 

<exp> 

<op> 

< value > 



= equal 

!= not equal 

& and 

I or 

> greater than 

< less than 

( ) used for logical groupings 

not may only occur immediately after the if, and 

when present, inverts the value of the 
entire condition 



The > and < operate only on unsigned integer values (e.g., : 012 > 12 is 
false). All other operators take strings as arguments (e.g., : 012 != 12 is 
true). The precedence of the operators (from highest to lowest) is: 

= != > < all of equal precedence 

& 

I 

Parentheses may be used to alter the order of precedence. 

Values must be separated from operators or parentheses by at least one 
blank or tab. 
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::text 

Used for keyword replacement on lines that are copied to the standard 
output. The two leading control characters are removed, and keywords 
surrounded by control characters in text are replaced by their value before 
the line is copied to the output file. This action is independent of the —a 
keyletter. 

:on 

:off 

Turn on or off keyword replacement on all lines. 

:ctl char 

Change the control character to char. 

:msg message 

Prints the given message on the diagnostic output. 

:err message 

Prints the given message followed by: 

ERROR: err statement on line ... (915) 

on the diagnostic output, vc halts execution, and returns an exit code of 1. 

SEE ALSO 

ed(l), help(l) in the User's Reference Manual. 

EXIT CODES 

0 — normal 

1 — any error 

Use help( 1) for explanations. 
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NAME 

what — identify SCCS files 

SYNOPSIS 

what [— s] files 

DESCRIPTION 

what searches the given files for all occurrences of the pattern that get( 1) substi- 
tutes for %Z% (this is @(#) at this printing) and prints out what follows until 
the first ~, >, new-line, \, or null character. For example, if the C program in 
file f.c contains 

char ident[] = "@(# identification information"; 
and f.c is compiled to yield f.o and a.out, then the command 



what f.c f.o a.out 


will print 




f.c: 


identification information 


f.o: 


identification information 


a.out: 


identification information 



what is intended to be used in conjunction with the command get( 1), which 
automatically inserts identifying information, but it can also be used where the 
information is inserted manually. Only one option exists: 

— s Quit after finding the first occurrence of pattern in each file. 

SEE ALSO 

get(l). 

help(l) in the User's Reference Manual. 

DIAGNOSTICS 

Exit status is 0 if any matches are found, otherwise 1. Use help( 1) for explana- 
tions. 

BUGS 

It is possible that an unintended occurrence of the pattern @(#) could be found 
just by chance, but this causes no harm in nearly all cases. 
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NAME 

wtinit — object downloader for the 5620 DMD terminal 
SYNOPSIS 

/usr /lib /lay ersys/ wtinit [— d] [— p] file 
DESCRIPTION 

The wtinit utility downloads the named file for execution in the AT&T Teletype 
5620 DMD terminal connected to its standard output, file must be a DMD object 
file, wtinit performs all necessary bootstrap and protocol procedures. 

There are two options. 

— d Prints out the sizes of the text, data, and bss portions of the downloaded 

file on standard error. 

— p Prints the down-loading protocol statistics and a trace on standard error. 

The environment variable JPATH is the analog of the shell's PATH variable to 
define a set of directories in which to search for file. 

If the environment variable DMDLOAD has the value hex, wtinit will use a hex- 
adecimal download protocol that uses only printable characters. 

Terminal Feature Packages for specific versions of AT&T windowing terminals 
will include terminal-specific versions of wtinit under those installation sub- 
directories. /usr /lib /lay ersys /wtinit is used for layers( 1) initialization only when 
no Terminal Feature Package is in use. 

DIAGNOSTICS 

Returns 0 upon successful completion, 1 otherwise. 

WARNING 

Standard error should be redirected when using the — d or — p options. 

SEE ALSO 

layers(l) in the User's Reference Manual. 
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NAME 

xtd — extract and print xt driver link structure 

SYNOPSIS 

xtd [-f] [-n ...] 

DESCRIPTION 

The xtd command is a debugging tool for the xt(7) driver. It performs an 
XTIOCDATA ioctl( 2) call on its standard input file to extract the Link data struc- 
ture for the attached group of channels. This call will fail if data extraction has 
not been configured in the driver or the standard input is not attached to an 
xt(7) channel. The data are printed one item per line on the standard output. 
The output should probably be formatted via pr -3. 

The optional flags affect output as follows: 

— n n is a number in the range 0 to 7. Channel n is included in the list of 
channels to be printed. The default prints all channels, whereas the 
occurrence of one or more channel numbers implies a subset. 

— f Causes a "formfeed" character to be put out at the end of the output, 
for the benefit of page-display programs. 

DIAGNOSTICS 

Returns 0 upon successful completion, 1 otherwise. 

SEE ALSO 

xts(lM), xtt(lM), ioctl(2), xtproto(5) in the Programmer's Reference Manual. 
xt (7) in the System Administrator's Reference Manual. 
pr(l) in the User's Reference Manual. 
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xts — extract and print xt driver statistics 

SYNOPSIS 

xts [-f] 

DESCRIPTION 

The xts command is a debugging tool for the xt(7) driver. It performs an 
XTIOCSTATS ioctl( 2) call on its standard input file to extract the accumulated 
statistics for the attached group of channels. This call will fail if statistics have 
not been configured in the driver or the standard input is not attached to an 
xt(7) channel. The statistics are printed one item per line on the standard 
output. 

— f Causes a "formfeed" character to be put out at the end of the output, 
for the benefit of page-display programs. 

DIAGNOSTICS 

Returns 0 upon successful completion, 1 otherwise. 

SEE ALSO 

xtd(lM), xtt(lM), ioctl(2), xtproto(5) in the Programmer's Reference Manual. 
xt (7) in the System Administrator's Reference Manual. 
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NAME 

xtt — extract and print xt driver packet traces 

SYNOPSIS 

xtt [-f] [-0] 

DESCRIPTION 

The xtt command is a debugging tool for the xt(7) driver. It performs an XTIOC- 
TRACE ioctl( 2) call on its standard input file to turn on tracing and extract the 
circular packet trace buffer for the attached group of channels. This call will fail 
if tracing has not been configured in the driver, or the standard input is not 
attached to an xt(7) channel. The packets are printed on the standard output. 

The optional flags are: 

— f Causes a "formfeed" character to be put out at the end of the output, for 

the benefit of page-display programs. 

— o Turns off further driver tracing. 

DIAGNOSTICS 

Returns 0 upon successful completion, 1 otherwise. 

NOTE 

If driver tracing has not been turned on for the terminal session by invoking 
layers( 1) with the — t option, xtt will not generate any output the first time it is 
executed. 

SEE ALSO 

xtd(lM), xts(lM), ioctl(2), layers(5) in the Programmer's Reference Manual. 
xt (7) in the System Administrator's Reference Manual. 
layers(l) in the User's Reference Manual. 
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NAME 

yacc — yet another compiler-compiler 
SYNOPSIS 

yacc [ — vdlt ] grammar 
DESCRIPTION 

The yacc command converts a context-free grammar into a set of tables for a 
simple automaton which executes an LR(1) parsing algorithm. The grammar may 
be ambiguous; specified precedence rules are used to break ambiguities. 

The output file, y.tab.c, must be compiled by the C compiler to produce a pro- 
gram yyparse. This program must be loaded with the lexical analyzer program, 
yylex, as well as main and yyerror, an error handling routine. These routines 
must be supplied by the user; lex( 1) is useful for creating lexical analyzers usable 
by yacc. 

If the —v flag is given, the file y.output is prepared, which contains a description 
of the parsing tables and a report on conflicts generated by ambiguities in the 
grammar. 

If the — d flag is used, the file y.tab.h is generated with the #define statements 
that associate the yacc-assigned "token codes" with the user-declared "token 
names". This allows source files other than y.tab.c to access the token codes. 

If the —1 flag is given, the code produced in y.tab.c will not contain any #Iine 
constructs. This should only be used after the grammar and the associated 
actions are fully debugged. 

Runtime debugging code is always generated in y.tab.c under conditional compi- 
lation control. By default, this code is not included when y.tab.c is compiled. 
However, when yacc ' s — t option is used, this debugging code will be compiled 
by default. Independent of whether the — t option was used, the runtime debug- 
ging code is under the control of YYDEBUG, a preprocessor symbol. If 
YYDEBUG has a non-zero value, then the debugging code is included. If its 
value is zero, then the code will not be included. The size and execution time of 
a program produced without the runtime debugging code will be smaller and 
slightly faster. 

FILES 

y.output 
y.tab.c 
y.tab.h 
yacc.tmp, 

yacc.debug, yacc.acts 
/usr /lib /yaccpar 

SEE ALSO 

lex(l). 

Programmer's Guide. 



defines for token names 
temporary files 

parser prototype for C programs 
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DIAGNOSTICS 

The number of reduce-reduce and shift-reduce conflicts is reported on the stan- 
dard error output; a more detailed report is found in the y. output file. Similarly, 
if some rules are not reachable from the start symbol, this is also reported. 

CAVEAT 

Because file names are fixed, at most one yacc process can be active in a given 
directory at a given time. 
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NAME 

intro — introduction to system calls and error numbers 
SYNOPSIS 

#include <errno.h> 

DESCRIPTION 

This section describes all of the system calls. Most of these calls have one or 
more error returns. An error condition is indicated by an otherwise impossible 
returned value. This is almost always —1 or the NULL pointer; the individual 
descriptions specify the details. An error number is also made available in the 
external variable errno. Errno is not cleared on successful calls, so it should be 
tested only after an error has been indicated. 

Each system call description attempts to list all possible error numbers. The fol- 
lowing is a complete list of the error numbers and their names as defined in 

<errno.h>. 

1 EPERM Not owner 

Typically this error indicates an attempt to modify a file in some way 
forbidden except to its owner or super-user. It is also returned for 
attempts by ordinary users to do things allowed only to the super-user. 

2 ENOENT No such file or directory 

This error occurs when a file name is specified and the file should exist 
but doesn't, or when one of the directories in a path name does not 
exist. 

3 ESRCH No such process 

No process can be found corresponding to that specified by pid in kill( 2) 
or ptrace( 2). 

4 EINTR Interrupted system call 

An asynchronous signal (such as interrupt or quit), which the user has 
elected to catch, occurred during a system call. If execution is resumed 
after processing the signal, it will appear as if the interrupted system call 
returned this error condition. 

5 EIO I/O error 

Some physical I/O error has occurred. This error may in some cases 
occur on a call following the one to which it actually applies. 

6 ENXIO No such device or address 

I/O on a special file refers to a subdevice which does not exist, or 
beyond the limits of the device. It may also occur when, for example, a 
tape drive is not on-line or no disk pack is loaded on a drive. 

7 E2BIG Arg list too long 

An argument list longer than 5,120 bytes is presented to a member of 
the exec (2) family. 

8 ENOEXEC Exec format error 

A request is made to execute a file which, although it has the 
appropriate permissions, does not start with a valid magic number [see 
a.out( 4)]. 
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9 EBADF Bad file number 

Either a file descriptor refers to no open file, or a read( 2) [respectively, 
write ( 2)] request is made to a file which is open only for writing (respec- 
tively, reading). 

10 ECHILD No child processes 

A wait was executed by a process that had no existing or unwaited-for 
child processes. 

11 EAGAIN No more processes 

A fork failed because the system's process table is full or the user is not 
allowed to create any more processes. Or a system call failed because of 
insufficient memory or swap space. 

12 ENOMEM Not enough space 

During an exec( 2), brk( 2), or sbrk( 2), a program asks for more space than 
the system is able to supply. This may not be a temporary condition; 
the maximum space size is a system parameter. The error may also 
occur if the arrangement of text, data, and stack segments requires too 
many segmentation registers, or if there is not enough swap space 
during a fork( 2). If this error occurs on a resource associated with 
Remote File Sharing (RFS), it indicates a memory depletion wich may be 
temporary, dependent on system activity at the time the call was 
invoked. 

13 EACCES Permission denied 

An attempt was made to access a file in a way forbidden by the protec- 
tion system. 

14 EFAULT Bad address 

The system encountered a hardware fault in attempting to use an argu- 
ment of a system call. 

15 ENOTBLK Block device required 

A non-block file was mentioned where a block device was required, e.g., 
in mount( 2). 

16 EBUSY Device or resource busy 

An attempt was made to mount a device that was already mounted or 
an attempt was made to dismount a device on which there is an active 
file (open file, current directory, mounted-on file, active text segment). It 
will also occur if an attempt is made to enable accounting when it is 
already enabled. The device or resource is currently unavailable. 

17 EEXIST File exists 

An existing file was mentioned in an inappropriate context, e.g., link( 2). 

18 EXDEV Cross-device link 

A link to a file on another device was attempted. 

19 ENODEV No such device 

An attempt was made to apply an inappropriate system call to a device; 
e.g., read a write-only device. 
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20 ENOTDIR Not a directory 

A non-directory was specified where a directory is required, for example 
in a path prefix or as an argument to chdir( 2). 

21 EISDIR Is a directory 

An attempt was made to write on a directory. 

22 EINVAL Invalid argument 

Some invalid argument (e.g., dismounting a non-mounted device; men- 
tioning an undefined signal in signal( 2) or kill(2); reading or writing a file 
for which lseek( 2) has generated a negative pointer). Also set by the 
math functions described in the (3M) entries of this manual. 

23 ENFILE File table overflow 

The system file table is full, and temporarily no more opens can be 
accepted. 

24 EMFILE Too many open files 

No process may have more than NOFILES (default 20) descriptors open 
at a time. 

25 ENOTTY Not a character device (or) Not a typewriter 

An attempt was made to ioctl( 2) a file that is not a special character 
device. 

26 ETXTBSY Text file busy 

An attempt was made to execute a pure-procedure program that is 
currently open for writing. Also an attempt to open for writing or to 
remove a pure-procedure program that is being executed. 

27 EFBIG File too large 

The size of a file exceeded the maximum file size or ULIMIT [see 
ulimit( 2)]. 

28 ENOSPC No space left on device 

During a write( 2) to an ordinary file, there is no free space left on the 
device. In fcntl( 2), the setting or removing of record locks on a file 
cannot be accomplished because there are no more record entries left on 
the system. 

29 ESPIPE Illegal seek 

An lseek( 2) was issued to a pipe. 

30 EROFS Read-only file system 

An attempt to modify a file or directory was made on a device mounted 
read-only. 

31 EMLINK Too many links 

An attempt to make more than the maximum number of links (1000) to 
a file. 

32 EPIPE Broken pipe 

A write on a pipe for which there is no process to read the data. This 
condition normally generates a signal; the error is returned if the signal 
is ignored. 
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33 EDOM Math argument 

The argument of a function in the math package (3M) is out of the 
domain of the function. 

34 ERANGE Result too large 

The value of a function in the math package (3M) is not representable 
within machine precision. 

35 ENOMSG No message of desired type 

An attempt was made to receive a message of a type that does not exist 
on the specified message queue [see msgop( 2)]. 

36 EIDRM Identifier removed 

This error is returned to processes that resume execution due to the 
removal of an identifier from the file system's name space [see msgctl( 2), 
semctl( 2), and shmctl( 2)]. 

37-44 Reserved numbers 

45 EDEADLK Deadlock 

A deadlock situation was detected and avoided. This error pertains to 
file and record locking. 

46 ENOLCK No lock 

In fcntl( 2) the setting or removing of record locks on a file cannot be 
accomplished because there are no more record entries left on the 
system. 

60 ENOSTR Not a stream 

A putmsg( 2) or getmsg( 2) system call was attempted on a file descriptor 
that is not a STREAMS device. 

62 ETIME Stream ioctl timeout 

The timer set for a STREAMS ioctl( 2) call has expired. The cause of this 
error is device specific and could indicate either a hardware or software 
failure, or perhaps a timeout value that is too short for the specific 
operation. The status of the ioctl( 2) operation is indeterminate. 

63 ENOSR No stream resources 

During a STREAMS open( 2), either no STREAMS queues or no STREAMS 
head data structures were available. 

64 ENONET Machine is not on the network 

This error is Remote File Sharing (RFS) specific. It occurs when users try 
to advertise, unadvertise, mount, or unmount remote resources while the 
machine has not done the proper startup to connect to the network. 

65 ENOPKG No package 

This error occurs when users attempt to use a system call from a 
package which has not been installed. 

66 EREMOTE Resource is remote 

This error is RFS specific. It occurs when users try to advertise a resource 
which is not on the local machine, or try to mount/unmount a device 
(or pathname) that is on a remote machine. 
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67 ENOLINK Virtual circuit is gone 

This error is RFS specific. It occurs when the link (virtual circuit) con- 
necting to a remote machine is gone. 

68 EADV Advertise error 

This error is RFS specific. It occurs when users try to advertise a resource 
which has been advertised already, or try to stop the RFS while there 
are resources still advertised, or try to force unmount a resource when it 
is still advertised. 

69 ESRMNT Srmount error 

This error is RFS specific. It occurs when users try to stop RFS while 
there are resources still mounted by remote machines. 

70 ECOMM Communication error 

This error is RFS specific. It occurs when trying to send messages to 
remote machines but no virtual circuit can be found. 

71 EPROTO Protocol error 

Some protocol error occurred. This error is device specific, but is gen- 
erally not related to a hardware failure. 

74 EMULTIHOP Multihop attempted 

This error is RFS specific. It occurs when users try to access remote 
resources which are not directly accessible. 

77 EBADMSG Bad message 

During a read( 2), getmsg( 2), or ioctl( 2) I_RECVFD system call to a 
STREAMS device, something has come to the head of the queue that 
can't be processed. That something depends on the system call: 
read( 2) - control information or a passed file descriptor. 
getmsg( 2) - passed file descriptor. 
ioctl( 2) - control or data information. 

83 ELIBACC Cannot access a needed shared library 

Trying to exec( 2) an a. out that requires a shared library (to be linked in) 
and the shared library doesn't exist or the user doesn't have permission 
to use it. 

84 ELIBBAD Accessing a corrupted shared library 

Trying to exec(2) an a.out that requires a shared library (to be linked in) 
and exec( 2) could not load the shared library. The shared library is prob- 
ably corrupted. 

85 ELIBSCN .lib section in a.out corrupted 

Trying to exec( 2) an a.out that requires a shared library (to be linked in) 
and there was erroneous data in the .lib section of the a.out. The .lib sec- 
tion tells exec( 2) what shared libraries are needed. The a.out is probably 
corrupted. 

86 ELIBMAX Attempting to link in more shared libraries than system limit 

Trying to exec( 2) an a.out that requires more shared libraries (to be 
linked in) than is allowed on the current configuration of the system. 
See the System Administrator's Guide. 
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87 ELIBEXEC Cannot exec a shared library directly 

Trying to exec( 2) a shared library directly. This is not allowed. 

DEFINITIONS 

Process ID Each active process in the system is uniquely identified by a positive 
integer called a process ID. The range of this ID is from 1 to 30,000. 

Parent Process ID A new process is created by a currently active process [see 
fork( 2)]. The parent process ID of a process is the process ID of its creator. 

Process Group ID Each active process is a member of a process group that is 
identified by a positive integer called the process group ID. This ID is the pro- 
cess ID of the group leader. This grouping permits the signaling of related 
processes [see kill (2)]. 

Tty Group ID Each active process can be a member of a terminal group that is 
identified by a positive integer called the tty group ID. This grouping is used to 
terminate a group of related processes upon termination of one of the processes 
in the group [see exit(2) and signal( 2)]. 

Real User ID and Real Group ID Each user allowed on the system is identified 
by a positive integer (0 to 65535) called a real user ID. 

Each user is also a member of a group. The group is identified by a positive 
integer called the real group ID. 

An active process has a real user ID and real group ID that are set to the real 
user ID and real group ID, respectively, of the user responsible for the creation of 
the process. 

Ejffective User ID and Effective Group ID An active process has an effective 
user ID and an effective group ID that are used to determine file access permis- 
sions (see below). The effective user ID and effective group ID are equal to the 
process's real user ID and real group ID respectively, unless the process or one of 
its ancestors evolved from a file that had the set-user-ID bit or set-group ID bit 
set [see exec( 2)]. 

Super-user A process is recognized as a super-user process and is granted spe- 
cial privileges, such as immunity from file permissions, if its effective user ID is 
0 . 

Special Processes The processes with a process ID of 0 and a process ID of 1 are 
special processes and are referred to as procO and procl. 
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ProcO is the scheduler. Prod is the initialization process ( init ). Procl is the 
ancestor of every other process in the system and is used to control the process 
structure. 

File Descriptor A file descriptor is a small integer used to do I/O on a file. The 
value of a file descriptor is from 0 to (NOFILES - 1). A process may have no 
more than NOFILES file descriptors open simultaneously. A file descriptor is 
returned by system calls such as open( 2), or pipe{ 2). The file descriptor is used 
as an argument by calls such as read( 2), write( 2), ioctl( 2), and close( 2). 

File Name Names consisting of 1 to 14 characters may be used to name an ordi- 
nary file, special file or directory. 

These characters may be selected from the set of all character values excluding 
\0 (null) and the ASCII code for / (slash). 

Note that it is generally unwise to use *, ?, [, or ] as part of file names because 
of the special meaning attached to these characters by the shell [see sh( 1)]. 
Although permitted, the use of unprintable characters in file names should be 
avoided. 

Path Name and Path Prefix A path name is a null-terminated character string 
starting with an optional slash (/), followed by zero or more directory names 
separated by slashes, optionally followed by a file name. 

If a path name begins with a slash, the path search begins at the root directory. 
Otherwise, the search begins from the current working directory. 

A slash by itself names the root directory. 

Unless specifically stated otherwise, the null path name is treated as if it named 
a non-existent file. 



Directory Directory entries are called links. By convention, a directory contains 
at least two links, . and referred to as dot and dot-dot respectively. Dot refers 
to the directory itself and dot-dot refers to its parent directory. 

Root Directory and Current Working Directory Each process has associated 
with it a concept of a root directory and a current working directory for the pur- 
pose of resolving path name searches. The root directory of a process need not 
be the root directory of the root file system. 

File Access Permissions Read, write, and execute/search permissions on a file 
are granted to a process if one or more of the following are true: 

The effective user ID of the process is super-user. 

The effective user ID of the process matches the user ID of the owner of 
the file and the appropriate access bit of the "owner" portion (0700) of 
the file mode is set. 
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The effective user ID of the process does not match the user ID of the 
owner of the file, and the effective group ID of the process matches the 
group of the file and the appropriate access bit of the "group" portion 
(0070) of the file mode is set. 

The effective user ID of the process does not match the user ID of the 
owner of the file, and the effective group ID of the process does not 
match the group ID of the file, and the appropriate access bit of the 
"other" portion (0007) of the file mode is set. 

Otherwise, the corresponding permissions are denied. 

Message Queue Identifier A message queue identifier (msqid) is a unique posi- 
tive integer created by a msgget( 2) system call. Each msqid has a message queue 
and a data structure associated with it. The data structure is referred to as 
msqid _ds and contains the following members: 

struct ipcjDerm msg^perm; 
struct msg *msg_first; 

struct msg *msg_last; 

ushort msgcbytes; 
ushort msgqnum; 
ushort msgqbytes; 
ushort msglspid; 
ushort msglrpid; 
timet msgstime; 
timet msgrtime; 
timet msgctime; 

msg_perm is an ipc_perm structure that specifies the message operation permis- 
sion (see below). This structure includes the following members: 



ushort 


cuid; 


/* creator user id */ 


ushort 


cgid; 


/* creator group id */ 


ushort 


uid; 


/* user id */ 


ushort 


gid; 


/* group id */ 


ushort 


mode; 


/* r/w permission */ 


ushort 


seq; 


/* slot usage sequence # */ 


key_t 


key; 


/* key */ 



msg *msg_first 

is a pointer to the first message on the queue. 

msg *msg_last 

is a pointer to the last message on the queue, 
msgcbytes 

is the current number of bytes on the queue. 

msgqnum 

is the number of messages currently on the queue. 

msgqbytes 

is the maximum number of bytes allowed on the queue. 
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msglspid 

is the process id of the last process that performed a msgsnd operation. 

msglrpid 

is the process id of the last process that performed a msgrcv operation. 

msgstime 

is the time of the last msgsnd operation. 

msgrtime 

is the time of the last msgrcv operation 

msgctime 

is the time of the last msgctl( 2) operation that changed a member of the 
above structure. 

Message Operation Permissions In the msgop( 2) and msgctl( 2) system call 
descriptions, the permission required for an operation is given as "{token}", 
where "token" is the type of permission needed, interpreted as follows: 



00400 


Read by user 


00200 


Write by user 


00040 


Read by group 


00020 


Write by group 


00004 


Read by others 


00002 


Write by others 



Read and write permissions on a msqid are granted to a process if one or more 
of the following are true: 

The effective user ID of the process is super-user. 

The effective user ID of the process matches msg_perm.cuid or 
msgjperm.uid in the data structure associated with msqid and the 
appropriate bit of the "user" portion (0600) of msg_perm.mode is set. 

The effective group ID of the process matches msg_perm.cgid or 
msgjjerm.gid and the appropriate bit of the "group" portion (060) of 
msg_perm.mode is set. 

The appropriate bit of the "other" portion (006) of msg_perm.mode is 
set. 

Otherwise, the corresponding permissions are denied. 

Semaphore Identifier A semaphore identifier (semid) is a unique positive 
integer created by a semget( 2) system call. Each semid has a set of semaphores 
and a data structure associated with it. The data structure is referred to as 
semid_ds and contains the following members: 

struct ipc^perm sem_perm; /* operation permission struct */ 
struct sem *sem_base; /* ptr to first semaphore in set */ 

ushort semnsems; /* number of sems in set */ 

time_t sem_otime; /* last operation time */ 

time_t sem_ctime; /* last change time */ 

/* Times measured in secs since */ 

/* 00:00:00 GMT, Jan. 1, 1970 */ 
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sem_perm is an ipc_perm structure that specifies the semaphore operation per- 
mission (see below). This structure includes the following members: 



ushort 


uid; 


/* user id */ 


ushort 


gid; 


/* group id */ 


ushort 


cuid; 


/* creator user id */ 


ushort 


cgid; 


/* creator group id */ 


ushort 


mode; 


/* r/a permission */ 


ushort 


seq; 


/* slot usage sequence number */ 


key_t 


key; 


/* key */ 



semnsems 

is equal to the number of semaphores in the set. Each semaphore in the 
set is referenced by a positive integer referred to as a semjium. 
Sem_num values run sequentially from 0 to the value of sem_nsems 
minus 1. 

semotime 

is the time of the last semop( 2) operation. 

semetime 

is the time of the last semctl( 2) operation that changed a member of the 
above structure. 



A semaphore is a data structure called sem that contains the following members: 



ushort semval; 
short sempid; 
ushort semnent; 
ushort semzcnt; 



/* semaphore value */ 

/* pid of last operation * / 

/* # awaiting semval > eval * / 
/* # awaiting semval = 0 */ 



semval 

is a non-negative integer which is the actual value of the semphore. 



sempid 

is equal to the process ID of the last process that performed a semaphore 
operation on this semaphore. 



semnent 

is a count of the number of processes that are currently suspended 
awaiting this semaphore's semval to become greater than its current 
value. 



semzcnt 

is a count of the number of processes that are currently suspended 
awaiting this semaphore's semval to become zero. 



Semaphore Operation Permissions In the semop{ 2) and semctl( 2) system call 
descriptions, the permission required for an operation is given as "{token}", 
where "token" is the type of permission needed interpreted as follows: 



00400 

00200 

00040 



Read by user 
Alter by user 
Read by group 
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00020 Alter by group 

00004 Read by others 

00002 Alter by others 

Read and alter permissions on a semid are granted to a process if one or more of 
the following are true: 

The effective user ID of the process is super-user. 

The effective user ID of the process matches semj>erm.cuid or 
semj>erm.uid in the data structure associated with semid and the 
appropriate bit of the "user" portion (0600) of sem_perm.mode is set. 

The effective group ID of the process matches sem^perm.cgid or 
semjperm.gid and the appropriate bit of the "group" portion (060) of 
semj>erm.mode is set. 

The appropriate bit of the "other" portion (006) of sem_perm.mode is 
set. 

Otherwise, the corresponding permissions are denied. 

Shared Memory Identifier A shared memory identifier (shmid) is a unique posi- 
tive integer created by a shmget( 2) system call. Each shmid has a segment of 
memory (referred to as a shared memory segment) and a data structure associ- 
ated with it. (Note that these shared memory segments must be explicitly 
removed by the user after the last reference to them is removed.) The data struc- 
ture is referred to as shmid_ds and contains the following members: 



struct 


ipc_p erm shm_perm; 


/* operation permission struct */ 


int 


shm_segsz; 


/* size of segment */ 


struct 


region *shm reg; 


/*ptr to region structure * / 


char 


pad[4]; 


/* for swap compatibility * / 


ushort 


shmlpid; 


/* pid of last operation * / 


ushort 


shmcpid; 


/* creator pid * / 


ushort 


shm_nattch; 


/* number of current attaches */ 


ushort 


shm_cnattch; 


/* used only for shminfo * / 


time_t 


shm_atime; 


/* last attach time */ 


time_t 


shm_dtime; 


/* last detach time */ 


time_t 


shm_ctime; 


/* last change time */ 

/ * Times measured in secs since * / 
/* 00:00:00 GMT, Jan. 1, 1970 */ 



shm_perm is an ipc_perm structure that specifies the shared memory operation 



permission (see below). 


This structure includes the following members: 


ushort 


cuid; 


/* creator user id */ 


ushort 


cgid; 


/* creator group id */ 


ushort 


uid; 


/* user id */ 


ushort 


gid; 


/* group id */ 


ushort 


mode; 


/* r/w permission */ 


ushort 


seq; 


/* slot usage sequence # */ 


keyj 


key; 


/* key */ 
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shmsegsz 

specifies the size of the shared memory segment in bytes. 

shmcpid 

is the process id of the process that created the shared memory 
identifier. 

shmlpid 

is the process id of the last process that performed a shmop( 2) operation. 

shmnattch 

is the number of processes that currently have this segment attached. 

shmatime 

is the time of the last shmat( 2) operation, 

shmdtime 

is the time of the last shmdt( 2) operation. 

shmctime 

is the time of the last shmctl( 2) operation that changed one of the 
members of the above structure. 

Shared Memory Operation Permissions In the shmop( 2) and shmctl{ 2) system 
call descriptions, the permission required for an operation is given as "{token)”, 
where "token" is the type of permission needed interpreted as follows: 



00400 


Read by user 


00200 


Write byotser 


00040 


Read by group 


00020 


Write by group 


00004 


Read by others 


00002 


Write by others 



Read and write permissions on a shmid are granted to a process if one or more 
of the following are true: 

The effective user ID of the process is super-user. 

The effective user ID of the process matches shm_perm.cuid or 
shm_perm.uid in the data structure associated with shmid and the 
appropriate bit of the "user" portion (0600) of shm_perm.mode is set. 

The effective group ID of the process matches shm_perm.cgid or 
shm_perm.gid and the appropriate bit of the "group" portion ( 060 ) of 
shmjperm.mode is set. 

The appropriate bit of the "other" portion (06) of shm_perm.mode is 
set. 

Otherwise, the corresponding permissions are denied. 

STREAMS A set of kernel mechanisms that support the development of network 
services and data communication drivers. It defines interface standards for char- 
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acter input/output within the kernel and between the kernel and user level 
processes. The STREAMS mechanism is composed of utility routines, kernel 
facilities and a set of data structures. 

Stream A stream is a full-duplex data path within the kernel between a user 
process and driver routines. The primary components are a stream head, a driver 
and zero or more modules between the stream head and driver. A stream is 
analogous to a Shell pipeline except that data flow and processing are bidirec- 
tional. x 

Stream Head In a stream, the stream head is the end of the stream that provides 
the interface between the stream and a user process. The principle functions of 
the stream head are processing STREAMS-related system calls, and passing data 
and information between a user process and the stream. 

Driver In a stream, the driver provides the interface between peripheral 
hardware and the stream. A driver can also be a pseu do-driver, such as a multi- 
plexor or log driver [see log(7)], which is not associated with a hardware device. 

Module A module is an entity containing processing routines for input and 
output data. It always exists in the middle of a stream, between the stream's 
head and a driver. A module is the STREAMS counterpart to the commands in a 
Shell pipeline except that a module contains a pair of functions which allow 
independent bidirectional ( downstream and upstream) data flow and processing. 

Downstream In a stream , the direction from stream head to driver. 

Upstream In a stream, the direction from driver to stream head. 

Message In a stream, one or more blocks of data or information, with associated 
STREAMS control structures. Messages can be of several defined types, which 
identify the message contents. Messages are the only means of transferring data 
and communicating within a stream. 

Message Queue In a stream, a linked list of messages awaiting processing by a 
module or driver. 

Read Queue In a stream, the message queue in a module or driver containing mes- 
sages moving upstream. 

Write Queue In a stream, the message queue in a module or driver containing 
messages moving downstream. 
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Multiplexor A multiplexor is a driver that allows streams associated with several 
user processes to be connected to a single driver , or several drivers to be con- 
nected to a single user process. STREAMS does not provide a general multi- 
plexing driver, but does provide the facilities for constructing them, and for con- 
necting multiplexed configurations of streams. 

SEE ALSO 

intro(3). 



137 




ACCESS(2) 



ACCESS(2) 



NAME 

access — determine accessibility of a file 
SYNOPSIS 

int access (path, amode) 
char *path; 
int amode; 

DESCRIPTION 

Path points to a path name naming a file, access checks the named file for 
accessibility according to the bit pattern contained in amode, using the real user 
ID in place of the effective user ID and the real group ID in place of the effective 
group ID. The bit pattern contained in amode is constructed as follows: 

04 read 

02 write 

01 execute (search) 

00 check existence of file 

Access to the file is denied if one or more of the following are true: 

[ENOTDIR] A component of the path prefix is not a directory. 
[ENOENT] Read, write, or execute (search) permission is 

requested for a null path name. 

[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied on a component of the 

path prefix. 

[EROFS] Write access is requested for a file on a read-only 

file system. 

[ETXTBSY] Write access is requested for a pure procedure 
(shared text) file that is being executed. 

[EACCES] Permission bits of the file mode do not permit 

the requested access. 

[EFAULT] Path points outside the allocated address 

space for the process. 

[EINTR] A signal was caught during the access 

system call. 

[ENOLINK] Path points to a remote machine and the link 
to that machine is no longer active. 

[EMULTIHOP] Components of path require hopping to multiple 
remote machines. 

The owner of a file has permission checked with respect to the "owner" read, 
write, and execute mode bits. Members of the file's group other than the owner 
have permissions checked with respect to the "group" mode bits, and all others 
have permissions checked with respect to the "other" mode bits. 

SEE ALSO 

chmod(2), stat(2). 

DIAGNOSTICS 

If the requested access is permitted, a value of 0 is returned. Otherwise, a value 
of —1 is returned and errno is set to indicate the error. 
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NAME 

acct — enable or disable process accounting 

SYNOPSIS 

int acct (path) 
char *path; 

DESCRIPTION 

acct is used to enable or disable the system process accounting routine. If the 
routine is enabled, an accounting record will be Written on an accounting file for 
each process that terminates. Termination can be caused by one of two things: 
an exit call or a signal [see exit( 2) and signal (2)]. The effective user ID of the cal- 
ling process must be super-user to use this call. 

path points to a pathname naming the accounting file. The accounting file 
format is given in acct (4). 

The accounting routine is enabled if path is non-zero and no errors occur during 
the system call. It is disabled if path is zero and no errors occur during the 
system call. 

acct will fail if one or more of the following are true: 

[EPERM] The effective user of the calling process is not super-user. 

[EBUSY] An attempt is being made to enable accounting when it is 

already enabled. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] One or more components of the accounting file path name do 

not exist. 

[EACCES] The file named by path is not an ordinary file. 

[EROFS] The named file resides on a read-only file system. 

[EFAULT] Path points to an illegal address. 

SEE ALSO 

exit(2), signal(2), acct(4). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 
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NAME 

alarm — set a process alarm clock 
SYNOPSIS 

unsigned alarm (sec) 
unsigned sec; 

DESCRIPTION 

alarm instructs the alarm clock of the calling process to send the signal SIGALRM 
to the calling process after the number of real time seconds specified by sec have 
elapsed [see signal ( 2)]. 

Alarm requests are not stacked; successive calls reset the alarm clock of the cal- 
ling process. 

If sec is 0, any previously made alarm request is canceled. 

SEE ALSO 

pause(2), signal(2), sigpause(2), sigset(2). 

DIAGNOSTICS 

alarm returns the amount of time previously remaining in the alarm clock of the 
calling process. 
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NAME 

brk, sbrk — change data segment space allocation 

SYNOPSIS 

int brk (endds) 
char *endds; 

char *sbrk (incr) 
int incr; 

DESCRIPTION 

brk and sbrk are used to change dynamically the amount of space allocated for 
the calling process's data segment [see exec (2)]. The change is made by resetting 
the process's break value and allocating the appropriate amount of space. The 
break value is the address of the first location beyond the end of the data seg- 
ment. The amount of allocated space increases as the break value increases. 
Newly allocated space is set to zero. If, however, the same memory space is 
reallocated to the same process its contents are undefined. 

brk sets the break value to endds and changes the allocated space accordingly. 

Sbrk adds incr bytes to the break value and changes the allocated space accord- 
ingly. Incr can be negative, in which case the amount of allocated space is 
decreased. 

brk and sbrk will fail without making any change in the allocated space if one or 
more of the following are true: 

[ENOMEM] Such a change would result in more space being allocated 
than is allowed by the system-imposed maximum process 
size [see ulimit( 2)]. 

[E AG AIN] Total amount of system memory available for a read 

during physical IO is temporarily insufficient [see 
shmop( 2)]. This may occur even though the space 
requested was less than the system-imposed maximum 
process size [see ulimit( 2)]. 

SEE ALSO 

exec(2), shmop(2), ulimit(2), end(3C). 

DIAGNOSTICS 

Upon successful completion, brk returns a value of 0 and sbrk returns the old 
break value. Otherwise, a value of —1 is returned and errno is set to indicate the 
error. 
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NAME 

chdir — change working directory 

SYNOPSIS 

int chdir (path) 
char *path; 

DESCRIPTION 

Path points to the path name of a directory, chdir causes the named directory to 
become the current working directory, the starting point for path searches for 
path names not beginning with /. 

chdir will fail and the current working directory will be unchanged if one or 
more of the following are true: 

[ENOTDIR] A component of the path name is not a directory. 

[ENOENT] The named directory does not exist. 

[EACCES] Search permission is denied for any component of the path 

name. 

[EFAULT] Path points outside the allocated address space of the process. 

[EINTR] A signal was caught during the chdir system call. 

[ENOLINK] Path points to a remote machine and the link to that machine is 
no longer active. 

[EMULTIHOP] Components of path require hoppiijig to multiple remote 
machines. 

SEE ALSO 

chroot(2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 
is returned and errno is set to indicate the error. 
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NAME 

chmod — change mode of file 
SYNOPSIS 

int chmod (path, mode) 
char *path; 
int mode; 

DESCRIPTION 

Path points to a path name naming a file, chmod sets the access permission por- 
tion of the named file's mode according to the bit pattern contained in mode. 

Access permission bits are interpreted as follows: 

04000 Set user ID on execution. 

020#0 Set group ID on execution if # is 7, 5, 3, or 1 

Enable mandatory file/record locking if # is 6, 4, 2, or 0 
01000 Save text image after execution. 

00400 Read by owner. 

00200 Write by owner. 

00100 Execute (search if a directory) by owner. 

00070 Read, write, execute (search) by group. 

00007 Read, write, execute (search) by others. 

The effective user ID of the process must match the owner of the file or be 
super-user to change the mode of a file. 

If the effective user ID of the process is not super-user, mode bit 01000 (save text 
image on execution) is cleared. 

If the effective user ID of the process is not super-user and the effective group ID 
of the process does not match the group ID of the file, mode bit 02000 (set 
group ID on execution) is cleared. 

If a 410 executable file has the sticky bit (mode bit 01000) set, the operating 
system will not delete the program text from the swap area when the last user 
process terminates. If a 413 executable file has the sticky bit set, the operating 
system will not delete the program text from memory when the last user process 
terminates. In either case, if the sticky bit is set the text will already be available 
(either in a swap area or in memory) when the next user of the file executes it, 
thus making execution faster. 

If the mode bit 02000 (set group ID on execution) is set and the mode bit 00010 
(execute or search by group) is not set, mandatory file/record locking will exist 
on a regular file. This may effect future calls to open(2), creat(2), read(2), and 
write(2) on this file. 

chmod will fail and the file mode will be unchanged if one or more of the fol- 
lowing are true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied on a component of the path prefix. 
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[EPERM] 

[EROFS] 

[EFAULT] 

[EINTR] 

[ENOLINK] 

[EMULTIHOP] 



The effective user ID does not match the owner of the file and 
the effective user ID is not super-user. 

The named file resides on a read-only file system. 

Path points outside the allocated address space of the process. 

A signal was caught during the chmod system call. 

Path points to a remote machine and the link to that machine is 
no longer active. 

Components of path require hopping to multiple remote 
machines. 



SEE ALSO 

chown(2), creat(2), fcntl(2), mknod(2), open(2), read(2), write(2). 
chmod(l) in the User's Reference Manual. 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of — 1 
is returned and errno is set to indicate the error. 
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NAME 

chown — change owner and group of a file 
SYNOPSIS 

int chown (path, owner, group) 

char *path; 

int owner, group; 



DESCRIPTION 

Path points to a path name naming a file. The owner ID and group ID of the 
named file are set to the numeric values contained in owner and group respec- 
tively. 

Only processes with effective user ID equal to the file owner or super-user may 
change the ownership of a file. 

If chown is invoked by other than the super-user, the set-user-ID and set-group- 
ID bits of the file mode, 04000 and 02000 respectively, will be cleared. 

chown will fail and the owner and group of the named file will remain 
unchanged if one or more of the following are true: 



[ENOTDIR] 

[ENOENT] 

[EACCES] 

[EPERM] 

[EROFS] 

[EFAULT] 

[EINTR] 

[ENOLINK] 

[EMULTIHOP] 



A component of the path prefix is not a directory. 

The named file does not exist. 

Search permission is denied on a component of the path prefix. 

The effective user ID does not match the owner of the file and 
the effective user ID is not super-user. 

The named file resides on a read-only file system. 

Path points outside the allocated address space of the process. 

A signal was caught during the chown system call. 

Path points to a remote machine and the link to that machine is 
no longer active. 

Components of path require hopping to multiple remote 
machines. 



SEE ALSO 

chmod(2). 

chown(l) in the User's Reference Manual. 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of — 1 
is returned and errno is set to indicate the error. 
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NAME 

chroot — change root directory 

SYNOPSIS 

int chroot (path) 
char *path; 



DESCRIPTION 

Path points to a path name naming a directory, chroot causes the named direc- 
tory to become the root directory, the starting point for path searches for path 
names beginning with /. The user's working directory is unaffected by the 
chroot system call. 

The effective user ID of the process must be super-user to change the root direc- 
tory. 



The .. entry in the root directory is interpreted to mean the root directory itself. 
Thus, .. cannot be used to access files outside the subtree rooted at the root 
directory. 

chroot will fail and the root directory will remain unchanged if one or more of 
the following are true: 



[ENOTDIR] 

[ENOENT] 

[EPERM] 

[EFAULT] 

[EINTR] 

[ENOLINK] 

[EMULTIHOP] 



Any component of the path name is not a directory. 

The named directory does not exist. 

The effective user ID is not super-user. 

Path points outside the allocated address space of the process. 

A signal was caught during the chroot system call. 

Path points to a remote machine and the link to that machine is 
no longer active. 

Components of path require hopping to multiple remote 
machines. 



SEE ALSO 

chdir(2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of — 1 
is returned and errno is set to indicate the error. 
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NAME 

close — close a file descriptor 

SYNOPSIS 

int close (fildes) 
int fildes; 

DESCRIPTION 

Fildes is a file descriptor obtained from a creat, open, dup, fcntl, or pipe system 
call, close closes the file descriptor indicated by fildes. All outstanding record 
locks owned by the process (on the file indicated by fildes) are removed. 

If a STREAMS [see intro( 2)] file is closed, and the calling process had previously 
registered to receive a SIGPOLL signal [see signal( 2) and sigset( 2)] for events asso- 
ciated with that file [see ISETSIG in streamio(7)], the calling process will be unre- 
gistered for events associated with the file. The last close for a stream causes the 
stream associated with fildes to be dismantled. If O NDELAY is not set and there 
have been no signals posted for the stream, close waits up to 15 seconds, for 
each module and driver, for any output to drain before dismantling the stream. 
If the 0_NDELAY flag is set or if there are any pending signals, close does not 
wait for output to drain, and dismantles the stream immediately. 

The named file is closed unless one or more of the following are true: 

[EBADF] Fildes is not a valid open file descriptor. 

[EINTR] A signal was caught during the close system call. 

[ENOLINK] Fildes is on a remote machine and the link to that machine is no 

longer ctive. 

SEE ALSO 

creat(2), dup(2), exec(2), fcntl(2), intro(2), open(2), pipe(2), signal(2), sigset(2). 
streamio(7) in the System Administrator's Reference Manual. 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 
is returned and errno is set to indicate the error. 
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NAME 

creat — create a new file or rewrite an existing one 
SYNOPSIS 

int creat (path, mode) 
char *path; 
int mode; 

DESCRIPTION 

creat creates a new ordinary file or prepares to rewrite an existing file named by 
the path name pointed to by path. 

If the file exists, the length is truncated to 0 and the mode and owner are 
unchanged. Otherwise, the file's owner ID is set to the effective user ID, of the 
process the group ID of the process is set to the effective group ID, of the process 
and the low-order 12 bits of the file mode are set to the value of mode modified 
as follows: 

All bits set in the process's file mode creation mask are cleared [see 
umask( 2)]. 

The "save text image after execution bit" of the mode is cleared [see 
chmod( 2)]. 

Upon successful completion, a write-only file descriptor is returned and the file 
is open for writing, even if the mode does not permit writing. The file pointer is 
set to the beginning of the file. The file descriptor is set to remain open across 
exec system calls [see fcntl( 2)]. No process may have more than 20 files open 
simultaneously. A new file may be created with a mode that forbids writing. 

creat fails if one or more of the following are true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] A component of the path prefix does not exist. 

[EACCES] Search permission is denied on a component of the path prefix. 

[ENOENT] The path name is null. 

[EACCES] The file does not exist and the directory in which the file is to 

be created does not permit writing. 

[EROFS] The named file resides or would reside on a read-only file 

system. 

[ETXTBSY] The file is a pure procedure (shared text) file that is being exe- 

cuted. 

[EACCES] The file exists and write permission is denied. 

[EISDIR] The named file is an existing directory. 

[EMFILE] NOFILES file descriptors are currently open. 

[EFAULT] Path points outside the allocated address space of the process. 

[ENFILE] The system file table is full. 

[E AG AIN] The file exists, mandatory file/record locking is set, and there 

are outstanding record locks on the file [see chmod( 2)]. 
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[EINTR] 

[ENOLINK] 

[EMULTIHOP] 



A signal was caught during the creat system call. 

Path points to a remote machine and the link to that machine is 
no longer active. 

Components of path require hopping to multiple remote 
machines. 



[ENOSPC] The file system is out of inodes. 

SEE ALSO 

chmod(2), close(2), dup(2), fcntl(2), lseek(2), open(2), read(2), umask(2), write(2). 
DIAGNOSTICS 

Upon successful completion, a non-negative integer, namely the file descriptor, 
is returned. Otherwise, a value of —1 is returned and errno is set to indicate the 
error. 
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NAME 

dup — duplicate an open file descriptor 

SYNOPSIS 

int dup (fildes) 
int fildes; 

DESCRIPTION 

Fildes is a file descriptor obtained from a creat, open, dup, fcntl, or pipe system 
call, dup returns a new file descriptor having the following in common with the 
original: 

Same open file (or pipe). 

Same file pointer (i.e., both file descriptors share one file pointer). 

Same access mode (read, write or read/ write). 

The new file descriptor is set to remain open across exec system calls [see 
fcntH 2)]. 

The file descriptor returned is the lowest one available. 
dup will fail if one or more of the following are true: 

[EBADF] Fildes is not a valid open file descriptor. 

[EINTR] A signal was caught during the dup system call. 

[EMFILE] NOFILES file descriptors are currently open. 

[ENOLINK] Fildes is on a remote machine and the link to that machine is no 

longer active. 

SEE ALSO 

close(2), creat(2), exec(2), fcntl(2), open(2), pipe(2), lockf(3C). 

DIAGNOSTICS 

Upon successful completion a non-negative integer, namely the file descriptor, is 
returned. Otherwise, a value of —1 is returned and errno is set to indicate the 
error. 
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NAME 

exec: execl, execv, execle, execve, execlp, execvp — execute a file 
SYNOPSIS 

int execl (path, argO, argl, ..., argn, (char *)0) 
char *path, *argO, *argl, ..., *argn; 

int execv (path, argv) 
char *path, *argv[ ]; 

int execle (path, argO, argl, ..., argn, (char *)0, envp) 
char *path, *argO, *argl, ..., *argn, *envp[ ]; 

int execve (path, argv, envp) 
char *path, *argv[ ], *envp[ ]; 

int execlp (file, argO, argl, ..., argn, (char *)0) 
char *file, *argO, *argl, ..., *argn; 

int execvp (file, argv) 
char *file, *argv[ ]; 

DESCRIPTION 

exec in all its forms transforms the calling process into a new process. The new 
process is constructed from an ordinary, executable file called the new process 
file. This file consists of a header [see a.out( 4)], a text segment, and a data seg- 
ment. The data segment contains an initialized portion and an uninitialized por- 
tion (bss). There can be no return from a successful exec because the calling 
process is overlaid by the new process. 

When a C program is executed, it is called as follows: 

main (argc, argv, envp) 
int argc; 

char **argv, **envp; 

where argc is the argument count, argv is an array of character pointers to the 
arguments themselves, and envp is an array of character pointers to the environ- 
ment strings. As indicated, argc is conventionally at least one and the first 
member of the array points to a string containing the name of the file. 

Path points to a path name that identifies the new process file. 

File points to the new process file. The path prefix for this file is obtained by a 
search of the directories passed as the environment line "PATH =" [see 
environ(5)]. The environment is supplied by the shell [see sh( 1)]. 

ArgO, argl, ..., argn are pointers to null-terminated character strings. These 
strings constitute the argument list available to the new process. By convention, 
at least argO must be present and point to a string that is the same as path (or its 
last component). 

Argv is an array of character pointers to null- terminated strings. These strings 
constitute the argument list available to the new process. By convention, argv 
must have at least one member, and it must point to a string that is the same as 
path (or its last component). Argv is terminated by a null pointer. 
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Envp is an array of character pointers to null-terminated strings. These strings 
constitute the environment for the new process. Envp is terminated by a null 
pointer. For execl and execv, the C run-time start-off routine places a pointer to 
the environment of the calling process in the global cell: 
extern char ** environ; 

and it is used to pass the environment of the calling process to the new process. 

File descriptors open in the calling process remain open in the new process, 
except for those whose close-on-exec flag is set; see fcntl( 2). For those file 
descriptors that remain open, the file pointer is unchanged. 

Signals set to terminate the calling process will be set to terminate the new pro- 
cess. Signals set to be ignored by the calling process will be set to be ignored by 
the new process. Signals set to be caught by the calling process will be set to 
terminate new process; see signal( 2). 

For signals set by s\gset( 2), exec will ensure that the new process has the same 
system signal action for each signal type whose action is SIGDFL, SIGJGN, or 
SIG_HOLD as the calling process. However, if the action is to catch the signal, 
then the action will be reset to SIGDFL, and any pending signal for this type 
will be held. 

If the set-user-ID mode bit of the new process file is set [see chmod( 2)], exec sets 
the effective user ID of the new process to the owner ID of the new process file. 
Similarly, if the set-group-ID mode bit of the new process file is set, the effective 
group ID of the new process is set to the group ID of the new process file. The 
real user ID and real group ID of the new process remain the same as those of 
the calling process. 

The shared memory segments attached to the calling process will not be 
attached to the new process [see shmop( 2)]. 

Profiling is disabled for the new process; see profil(2). 

The new process also inherits the following attributes from the calling process: 

nice value [see nice (2)] 

process ID 

parent process ID 

process group ID 

semadj values [see semop(2)\ 

tty group Ip [see exit( 2) and signal( 2)] 

trace flag fsee ptrace( 2) request 0] 

time left until an alarm clock signal [see alarm( 2)] 

current working directory 

root directory 

file mode creation mask [see umask( 2)] 
file size limit [see ulimit( 2)] 
utime, stime, cutime, and cstime [see times( 2)] 
file-locks [see fcntl( 2) and lockf( 3C)] 

exec will fail and return to the calling process if one or more of the following are 
true: 
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[ENOENT] 

[ENOTDIR] 

[EACCES] 

[EACCES] 

[EACCES] 

[ENOEXEC] 



[ETXTBSY] 

[ENOMEM] 

[E2BIG] 

[EFAULT] 

[EFAULT] 

[EFAULT] 

[EAGAIN] 

[ELIBACC] 

[ELIBEXEC] 

[EINTR] 

[ENOLINK] 

[EMULTIHOP] 



One or more components of the new process path name of the 
file do not exist. 

A component of the new process path of the file prefix is not a 
directory. 

Search permission is denied for a directory listed in the new 
process file's path prefix. 

The new process file is not an ordinary file. 

The new process file mode denies execution permission. 

The exec is not an execlp or execvp , and the new process file 
has the appropriate access permission but an invalid magic 
number in its header. 

The new process file is a pure procedure (shared text) file that is 
currently open for writing by some process. 

The new process requires more memory than is allowed by the 
system-imposed maximum MAXMEM. 

The number of bytes in the new process's argument list is 
greater than the system-imposed limit of 5120 bytes. 

Required hardware is not present. 

An a.out that was compiled with the MAU or 32B flag is run- 
ning on a machine without a MAU or 32B. 

Path, argv, or envp point to an illegal address. 

Not enough memory. 

Required shared library does not have execute permission. 
Trying to exec( 2) a shared library directly. 

A signal was caught during the exec system call. 

Path points to a remote machine and the link to that machine is 
no longer active. 

Components of path require hopping to multiple remote 
machines. 



SEE ALSO 

alarm(2), exit(2), fcntl(2), fork(2), nice(2), ptrace(2), semop(2), signal(2), sigset(2), 
times(2), ulimit(2), umask(2), lockf(3C), a.out(4), environ(5). 
sh(l) in the User's Reference Manual. 

DIAGNOSTICS 

If exec returns to the calling process an error has occurred; the return value will 
be —1 and errno will be set to indicate the error. 
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NAME 

exit, _exit — terminate process 

SYNOPSIS 

void exit (status) 
int status; 
void exit (status) 
int status; 

DESCRIPTION 

exit terminates the calling process with the following consequences: 

All of the file descriptors open in the calling process are closed. 

If the parent process of the calling process is executing a wait, it is notified of 
the calling process's termination and the low order eight bits (i.e., bits 0377) of 
status are made available to it [see wait (2)]. 

If the parent process of the calling process is not executing a wait, the calling 
process is transformed into a zombie process. A zombie process is a process that 
only occupies a slot in the process table. It has no other space allocated either 
in user or kernel space. The process table slot that it occupies is partially over- 
laid with time accounting information (see <sys/proc.h>) to be used by times. 

The parent process ID of all of the calling processes' existing child processes and 
zombie processes is set to 1. This means the initialization process [see intro ( 2)] 
inherits each of these processes. 

Each attached shared memory segment is detached and the value of 
shm nattach in the data structure associated with its shared memory identifier is 
decremented by 1. 

For each semaphore for which the calling process has set a semadj value [see 
semop( 2)\, that semadj value is added to the semval of the specified semaphore. 

If the process has a process, text, or data lock, an unlock is performed [see 
plock( 2)]. 

An accounting record is written on the accounting file if the system's accounting 
routine is enabled [see acct( 2)]. 

If the process ID, tty group ID, and process group ID of the calling process are 
equal, the SIGHUP signal is sent to each process that has a process group ID 
equal to that of the calling process. 

A death of child signal is sent to the parent. 

The C function exit may cause cleanup actions before the process exits. The 
function exit circumvents all cleanup. 
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SEE ALSO 

acct(2), intro(2), plock(2), semop(2), signal(2), sigset(2), wait(2). 
WARNING 

See WARNING in signal (2). 

DIAGNOSTICS 

None. There can be no return from an exit system call. 
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NAME 

fcntl — file control 
SYNOPSIS 

#include <fcntl.h> 

int fcntl (fildes, cmd, arg) 
int fildes, cmd, arg; 

DESCRIPTION 

fcntl provides for control over open files. Fildes is an open file descriptor 
obtained from a creat, open , dup, fcntl, or pipe system call. 

The commands available are: 

F DUPFD Return a new file descriptor as follows: 

Lowest numbered available file descriptor greater than or equal 
to arg. 

Same open file (or pipe) as the original file. 

Same file pointer as the original file (i.e., both file descriptors 
share one file pointer). 

Same access mode (read, write or read/ write). 

Same file status flags (i.e., both file descriptors share the same 
file status flags). 

The close-on-exec flag associated with the new file descriptor 
is set to remain open across exec (2) system calls. 

F GETFD Get the close-on-exec flag associated with the file descriptor 

fildes. If the low-order bit is 0 the file will remain open across 
exec , otherwise the file will be closed upon execution of exec. 

F SETFD Set the close-on-exec flag associated with fildes to the low- 

order bit of arg (0 or 1 as above). 

F GETFL Get file status flags. 

F SETFL Set file status flags to arg. Only certain flags can be set [see 

fcntl(5)]. 

F GETLK Get the first lock which blocks the lock description given by 

the variable of type struct flock pointed to by arg. The infor- 
mation retrieved overwrites the information passed to fcntl in 
the flock structure. If no lock is found that would prevent this 
lock from being created, then the structure is passed back 
unchanged except for the lock type which will be set to 
FJJNLCK. 

F SETLK Set or clear a file segment lock according to the variable of 

type struct flock pointed to by arg [see fcntl(5)]. The cmd 
F_SETLK is used to establish read (F RDLCK) and write 
(F WRLCK) locks, as well as remove either type of lock 
(FJJNLCK). If a read or write lock cannot be set fcntl will 
return immediately with an error value of —1. 
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FSETLKW This cmd is the same as FSETLK except that if a read or write 

lock is blocked by other locks, the process will sleep until the 
segment is free to be locked. 

A read lock prevents any process from write locking the protected area. More 
than one read lock may exist for a given segment of a file at a given time. The 
file descriptor on which a read lock is being placed must have been opened with 
read access. 

A write lock prevents any process from read locking or write locking the pro- 
tected area. Only one write lock may exist for a given segment of a file at a 
given time. The file descriptor on which a write lock is being placed must have 
been opened with write access. 

The structure flock describes the type (Ijype), starting offset ( Ijvhence ), relative 
offset ( l_start ), size ( l Jen ), process id ( l_pid ), and RFS system id (l_sysid) of the 
segment of the file to be affected. The process id and system id fields are used 
only with the FGETLK cmd to return the values for a blocking lock. Locks may 
start and extend beyond the current end of a file, but may not be negative rela- 
tive to the beginning of the file. A lock may be set to always extend to the end 
of file by setting l Jen to zero (0). If such a lock also has Ijvhence and l_start set 
to zero (0), the whole file will be locked. Changing or unlocking a segment 
from the middle of a larger locked segment leaves two smaller segments for 
either end. Locking a segment that is already locked by the calling process 
causes the old lock type to be removed and the new lock type to take effect. All 
locks associated with a file for a given process are removed when a file 
descriptor for that file is closed by that process or the process holding that file 
descriptor terminates. Locks are not inherited by a child process in a fork( 2) 
system call. 

When mandatory file and record locking is active on a file, [see chmod( 2)], read 
and write system calls issued on the file will be affected by the record locks in 
effect. 

fcntl will fail if one or more of the following are true: 

[EBADF] Fildes is not a valid open file descriptor. 

[EINVAL] Cmd is F DUPFD. arg is either negative, or greater than or equal 

to the configured value for the maximum number of open file 
descriptors allowed each user. 

[EINVAL] Cmd is F_GETLK, F SETLK, or SETLKW and arg or the data it 

points to is not valid. 

[EACCES] Cmd is F SETLK the type of lock (Ijype) is a read (F RDLCK) lock 

and the segment of a file to be locked is already write locked by 
another process or the type is a write (F WRLCK) lock and the 
segment of a file to be locked is already read or write locked by 
another process. 
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[ENOLCK] Cmd is F_SETLK or F_SETLKW, the type of lock is a read or write 

lock, and there are no more record locks available (too many 
file segments locked) because the system maximum has been 
exceeded. 



[EDEADLK] 



[EFAULT] 

[EINTR] 

[ENOLINK] 



Cmd is FSETLKW, the lock is blocked by some lock from 
another process, and putting the calling-process to sleep, 
waiting for that lock to become free, would cause a deadlock. 

Cmd is FSETLK, arg points outside the program address space. 

A signal was caught during the fcntl system call. 

Tildes is on a remote machine and the link to that machine is no 
longer active. 



SEE ALSO 

close(2), creat(2), dup(2), exec(2), fork(2), open(2), pipe(2), fcntl(5). 
DIAGNOSTICS 

Upon successful completion, the value returned depends on cmd as follows: 



FJDUPFD 


A new file descriptor. 


FGETFD 


Value of flag (only the low-order bit is defined). 


F SETFD 


Value other than —1. 


FGETFL 


Value of file flags. 


FSETFL 


Value other than —1. 


F GETLK 


Value other than —1. 


FSETLK 


Value other than —1. 


F SETLKW 


Value other than —1. 



Otherwise, a value of —1 is returned and errno is set to indicate the error. 



WARNINGS 

Because in the future the variable errno will be set to EAGAIN rather than 
EACCES when a section of a file is already locked by another process, portable 
application programs should expect and test for either value. 
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NAME 

fork — create a new process 

SYNOPSIS 

int fork () 

DESCRIPTION 

fork causes creation of a new process. The new process (child process) is an 
exact copy of the calling process (parent process). This means the child process 
inherits the following attributes from the parent process: 

environment 

close-on-exec flag [see exec (2)] 

signal handling settings (i.e., SIG DFL, SIG IGN, SIG HOLD, function 
address) 

set-user-ID mode bit 
set-group-ID mode bit 
profiling on/off status 
nice value [see nice (2)] 

all attached shared memory segments [see shmop( 2)] 

process group ID 

tty group ID [see exit{2)\ 

current working directory 

root directory 

file mode creation mask [see u mas k (2)] 
file size limit [see ulimit( 2)] 

The child process differs from the parent process in the following ways: 

The child process has a unique process ID. 

The child process has a different parent process ID (i.e., the process ID of 
the parent process). 

The child process has its own copy of the parent's file descriptors. Each 
of the child's file descriptors shares a common file pointer with the 
corresponding file descriptor of the parent. 

All semadj values are cleared [see semop{ 2)]. 

Process locks, text locks and data locks are not inherited by the child 
[see plock(2)]. 

The child process's utime, stime, cutime, and cstime are set to 0. The 
time left until an alarm clock signal is reset to 0. 

fork will fail and no child process will be created if one or more of the following 
are true: 

[EAGAIN] The system-imposed limit on the total number of processes 

under execution would be exceeded. 

[EAGAIN] The system-imposed limit on the total number of processes 

under execution by a single user would be exceeded. 

[EAGAIN] Total amount of system memory available when reading via 

raw IO is temporarily insufficient. 



159 




FORK(2) 



FORK(2) 



SEE ALSO 

exec(2), nice(2), plock(2), ptrace(2), semop(2), shmop(2), signal(2), sigset(2), 
times(2), ulimit(2), umask(2), wait(2). 

DIAGNOSTICS 

Upon successful completion, fork returns a value of 0 to the child process and 
returns the process ID of the child process to the parent process. Otherwise, a 
value of —1 is returned to the parent process, no child process is created, and 
errno is set to indicate the error. 
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NAME 

getdents — read directory entries and put in a file system independent format 
SYNOPSIS 

#include <sys/dirent.h> 

int getdents (tildes, but, nbyte) 
int fildes; 
char *buf; 
unsigned nbyte; 

DESCRIPTION 

Fildes is a file descriptor obtained from an open( 2) or dup( 2) system call. 

getdents attempts to read nbyte bytes from the directory associated with fildes 
and to format them as file system independent directory entries in the buffer 
pointed to by buf. Since the file system independent directory entries are of 
variable length, in most cases the actual number of bytes returned will be strictly 
less than nbyte. 

The file system independent directory entry is specified by the dirent structure. 
For a description of this see dirent (4). 

On devices capable of seeking, getdents starts at a position in the file given by 
the file pointer associated with fildes. Upon return from getdents , the file pointer 
is incremented to point to the next directory entry. 

This system call was developed in order to implement the readdir( 3X) routine 
[for a description see directory (3X)], and should not be used for other purposes. 

getdents will fail if one or more of the following are true: 

[EBADF] Fildes is not a valid file descriptor open for reading. 

[EFAULT] Buf points outside the allocated address space. 

[EINVAL] nbyte is not large enough for one directory entry. 

[ENOENT] The current file pointer for the directory is not located at a valid 

entry. 

[ENOLINK] Fildes points to a remote machine and the link to that machine 
is no longer active. 

[ENOTDIR] Fildes is not a directory. 

[EIO] An I/O error occurred while accessing the file system. 

SEE ALSO 

directory (3X), dirent(4). 

DIAGNOSTICS 

Upon successful completion a non-negative integer is returned indicating the 
number of bytes actually read. A value of 0 indicates the end of the directory 
has been reached. If the system call failed, a —1 is returned and errno is set to 
indicate the error. 
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NAME 

getmsg — get next message off a stream 
SYNOPSIS 

#include <stropts.h> 

int getmsg(fd, ctlptr, dataptr, flags) 
int fd; 

struct strbuf * ctlptr; 
struct strbuf * dataptr; 
int *flags; 

DESCRIPTION 

getmsg retrieves the contents of a message [see intro( 2)] located at the stream 
head read queue from a STREAMS file, and places the contents into user specified 
buffer(s). The message must contain either a data part, a control part or both. 
The data and control parts of the message are placed into separate buffers, as 
described below. The semantics of each part is defined by the STREAMS module 
that generated the message. 

Fd specifies a file descriptor referencing an open stream. Ctlptr and dataptr each 
point to a strbuf structure which contains the following members: 

int maxlen; /* maximum buffer length */ 
int len; /* length of data */ 

char *buf; /* ptr to buffer */ 

where buf points to a buffer in which the data or control information is to be 
placed, and maxlen indicates the maximum number of bytes this buffer can hold. 
On return, len contains the number of bytes of data or control information actu- 
ally received, or is 0 if there is a zero-length control or data part, or is -1 if no 
data or control information is present in the message. Flags may be set to the 
values 0 or RSJHIPRI and is used as described below. 

Ctlptr is used to hold the control part from the message and dataptr is used to 
hold the data part from the message. If ctlptr (or dataptr) is NULL or the maxlen 
field is -1, the control (or data) part of the message is not processed and is left 
on the stream head read queue and len is set to -1. If the maxlen field is set to 0 
and there is a zero-length control (or data) part, that zero-length part is removed 
from the read queue and len is set to 0. If the maxlen field is set to 0 and there 
are more than zero bytes of control (or data) information, that information is left 
on the read queue and len is set to 0. If the maxlen field in ctlptr or dataptr is 
less than, respectively, the control or data part of the message, maxlen bytes are 
retrieved. In this case, the remainder of the message is left on the stream head 
read queue and a non-zero return value is provided, as described below under 
DIAGNOSTICS. If information is retrieved from a priority message, flags is set to 
RSHIPRI on return. 

By default, getmsg processes the first priority or non-priority message available 
on the stream head read queue. However, a user may choose to retrieve only 
priority messages by setting flags to RS HIPRI. In this case, getmsg will only pro- 
cess the next message if it is a priority message. 

If O NDELAY has not been set, getmsg blocks until a message, of the type(s) 
specified by flags (priority or either), is available on the stream head read queue. 
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If ONDELAY has been set and a message of the specified type(s) is not present 
on the read queue, getmsg fails and sets errno to EAGAIN. 

If a hangup occurs on the stream from which messages are to be retrieved, 
getmsg will continue to operate normally, as described above, until the stream 
head read queue is empty. Thereafter, it will return 0 in the len fields of ctlptr 
and dataptr. 

getmsg fails if one or more of the following are true: 



[EAGAIN] 

[EBADF] 

[EBADMSG] 

[EFAULT] 

[EINTR] 

[EINVAL] 

[ENOSTR] 



The O NDELAY flag is set, and no messages are available. 

Fd is not a valid file descriptor open for reading. 

Queued message to be read is not valid for getmsg . 

Ctlptr, dataptr, or flags points to a location outside the allocated 
address space. 

A signal was caught during the getmsg system call. 

An illegal value was specified in flags, or the stream referenced 
by fd is linked under a multiplexor. 

A stream is not associated with fd. 



A getmsg can also fail if a STREAMS error message had been received at the 
stream head before the call to getmsg. The error returned is the value contained 
in the STREAMS error message. 



SEE ALSO 

intro(2), read(2), poll(2), putmsg(2), write(2). 

STREAMS Primer 

STREAMS Programmer's Guide 



DIAGNOSTICS 

Upon successful completion, a non-negative value is returned. A value of 0 
indicates that a full message was read successfully. A return value of MORECTL 
indicates that more control information is waiting for retrieval. A return value of 
MOREDATA indicates that more data is waiting for retrieval. A return value of 
MORECTL|MOREDATA indicates that both types of information remain. Subse- 
quent getmsg calls will retrieve the remainder of the message. 
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NAME 

getpid, getpgrp, getppid — get process, process group, and parent process IDs 

SYNOPSIS 

int getpid () 

int getpgrp () 
int getppid () 

DESCRIPTION 

getpid returns the process ID of the calling process. 

Getpgrp returns the process group ID of the calling process. 

Getppid returns the parent process ID of the calling process. 

SEE ALSO 

exec(2), fork(2), intro(2), setpgrp(2), signal(2). 
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NAME 

getuid, geteuid, getgid, getegid — get real user, effective user, real group, and 
effective group IDs 

SYNOPSIS 

unsigned short getuid () 
unsigned short geteuid () 
unsigned short getgid () 
unsigned short getegid () 

DESCRIPTION 

getuid returns the real user ID of the calling process. 

Geteuid returns the effective user ID of the calling process. 

Getgid returns the real group ID of the calling process. 

Getegid returns the effective group ID of the calling process. 

SEE ALSO 

intro(2), setuid(2). 
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NAME 

ioctl — control device 
SYNOPSIS 

int ioctl (fildes, request, arg) 
int fildes, request; 

DESCRIPTION 

ioctl performs a variety of control functions on devices and STREAMS. For non- 
STREAMS files, the functions performed by this call are device-specific control 
functions. The arguments request and arg are passed to the file designated by 
fildes and are interpreted by the device driver. This control is infrequently used 
on non-STREAMS devices, with the basic input/output functions performed 
through the read( 2) and zvrite( 2) system calls. 

For STREAMS files, specific functions are performed by the ioctl call as described 
in streamio(7). 

Fildes is an open file descriptor that refers to a device. Request selects the con- 
trol function to be performed and will depend on the device being addressed. 
Arg represents additional information that is needed by this specific device to 
perform the requested function. The data type of arg depends upon the partic- 
ular control request, but it is either an integer or a pointer to a device-specific 
data structure. 

In addition to device-specific and STREAMS functions, generic functions are pro- 
vided by more than one device driver, for example, the general terminal inter- 
face [see termio(7)]. 

ioctl will fail for any type of file if one or more of the following are true: 

[EBADF] Fildes is not a valid open file descriptor. 

[ENOTTY] Fildes is not associated with a device driver that accepts control 

functions. 

[EINTR] A signal was caught during the ioctl system call. 

ioctl will also fail if the device driver detects an error. In this case, the error is 
passed through ioctl without change to the caller. A particular driver might not 
have all of the following error cases. Other requests to device drivers will fail if 
one or more of the following are true: 

[EFAULT] Request requires a data transfer to or from a buffer pointed to 
by arg, but some part of the buffer is outside the process's allo- 
cated space. 

[EINVAL] Request or arg is not valid for this device. 

[EIO] Some physical I/O error has occurred. 

[ENXIO] The request and arg are valid for this device driver, but the ser- 

vice requested can not be performed on this particular sub- 
device. 
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[ENOLINK] Fildes is on a remote machine and the link to that machine is no 
longer active. 

STREAMS errors are described in streamio(7). 

SEE ALSO 

streamio(7), termio(7) in the System Administrator's Reference Manual 
DIAGNOSTICS 

Upon successful completion, the value returned depends upon the device control 
function, but must be a non-negative integer. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 
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NAME 

kill — send a signal to a process or a group of processes 

SYNOPSIS 

int kill (pid, sig) 
int pid, sig; 

DESCRIPTION 

kill sends a signal to a process or a group of processes. The process or group of 
processes to which the signal is to be sent is specified by pid. The signal that is 
to be sent is specified by sig and is either one from the list given in signal( 2), or 
0. If sig is 0 (the null signal), error checking is performed but no signal is actu- 
ally sent. This can be used to check the validity of pid. 

The real or effective user ID of the sending process must match the real or 
effective user ID of the receiving process, unless the effective user ID of the 
sending process is super-user. 

The processes with a process ID of 0 and a process ID of 1 are special processes 
[see intro( 2)] and will be referred to below as procO and prod, respectively. 

If pid is greater than zero, sig will be sent to the process whose process ID is 
equal to pid. Pid may equal 1. 

If pid is 0, sig will be sent to all processes excluding procO and prod whose pro- 
cess group ID is equal to the process group ID of the sender. 

If pid is —1 and the effective user ID of the sender is not super-user, sig will be 
sent to all processes excluding procO and prod whose real user ID is equal to the 
effective user ID of the sender. 

If pid is —1 and the effective user ID of the sender is super-user, sig will be sent 
to all processes excluding procO and prod. 

If pid is negative but not — 1, sig will be sent to all processes whose process 
group ID is equal to the absolute value of pid. 

kill will fail and no signal will be sent if one or more of the following are true: 
[EINVAL] Sig is not a valid signal number. 

[EINVAL] Sig is SIGKILL and pid is 1 (procl). 

[ESRCH] No process can be found corresponding to that specified by pid. 

[EPERM] The user ID of the sending process is not super-user, and its real 

or effective user ID does not match the real or effective user ID 
of the receiving process. 

SEE ALSO 

getpid(2), setpgrp(2), signal(2), sigset(2). 
kill(l) in the User's Reference Manual. 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 
is returned and errno is set to indicate the error. 
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NAME 

link — link to a file 
SYNOPSIS 

int link (pathl, path2) 
char *pathl, *path2; 

DESCRIPTION 

Pathl points to a path name naming an existing file. Path2 points to a path 
name naming the new directory entry to be created, link creates a new link 
(directory entry) for the existing file. 

link will fail and no link will be created if one or more of the following are true: 
[ENOTDIR] A component of either path prefix is not a directory. 

[ENOENT] A component of either path prefix does not exist. 

[EACCES] A component of either path prefix denies search permission. 

[ENOENT] The file named by pathl does not exist. 

[EEXIST] The link named by pathl exists. 

[EPERM] The file named by pathl is a directory and the effective user ID 

is not super-user. 

[EXDEV] The link named by pathl and the file named by pathl are on 

different logical devices (file systems). 

[ENOENT] Pathl points to a null path name. 

[EACCES] The requested link requires writing in a directory with a mode 

that denies write permission. 

[EROFS] The requested link requires writing in a directory on a read-only 

file system. 

[EFAULT] Path points outside the allocated address space of the process. 

[EMLINK] The maximum number of links to a file would be exceeded. 

[EINTR] A signal was caught during the link system call. 

[ENOLINK] Path points to a remote machine and the link to that machine is 
no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

SEE ALSO 

unlink(2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 
is returned and errno is set to indicate the error. 



169 




LSEEK(2) 



LSEEK(2) 



NAME 

lseek — move read/ write file pointer 
SYNOPSIS 

long lseek (tildes, offset, whence) 
int tildes; 
long offset; 
int whence; 

DESCRIPTION 

Tildes is a file descriptor returned from a creat, open, dup, or fcntl system call. 
lseek sets the file pointer associated with fildes as follows: 

If whence is 0, the pointer is set to offset bytes. 

If whence is 1, the pointer is set to its current location plus offset. 

If whence is 2, the pointer is set to the size of the file plus offset. 

Upon successful completion, the resulting pointer location, as measured in bytes 
from the beginning of the file, is returned. Note that if fildes is a remote file 
descriptor and offset is negative, lseek will return the file pointer even if it is 
negative. 

lseek will fail and the file pointer will remain unchanged if one or more of the 
following are true: 

[EBADF] Fildes is not an open file descriptor. 

[ESPIPE] Fildes is associated with a pipe or fifo. 

[EINVAL and SIGSYS signal] 

Whence is not 0, 1, or 2. 

[EINVAL] Fildes is not a remote file descriptor, and the resulting file 
pointer would be negative. 

Some devices are incapable of seeking. The value of the file pointer associated 
with such a device is undefined. 

SEE ALSO 

creat(2), dup(2), fcntl(2), open(2). 

DIAGNOSTICS 

Upon successful completion, a non-negative integer indicating the file pointer 
value is returned. Otherwise, a value of —1 is returned and errno is set to indi- 
cate the error. 
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NAME 

mkdir — make a directory 
SYNOPSIS 

int mkdir (path, mode) 
char *path; 
int mode; 



DESCRIPTION 

The routine mkdir creates a new directory with the name path. The mode of the 
new directory is initialized from the mode. The protection part of the mode argu- 
ment is modified by the process's mode mask [see umask( 2)]. 

The directory's owner ID is set to the process's effective user ID. The directory's 
group ID is set to the process's effective group ID. The newly created directory 
is empty with the possible exception of entries for and mkdir will fail and 
no directory will be created if one or more of the following are true: 



[ENOTDIR] 

[ENOENT] 

[ENOLINK] 

[EMULTIHOP] 



A component of the path prefix is not a directory. 

A component of the path prefix does not exist. 

Path points to a remote machine and the link to that machine is 
no longer active. 

Components of path require hopping to multiple remote 
machines. 



[EACCES] 



[ENOENT] 

[EEXIST] 

[EROFS] 

[EFAULT] 

[EMLINK] 



Either a component of the path prefix denies search permission 
or write permission is denied on the parent directory of the 
directory to be created. 

The path is longer than the maximum allowed. 

The named file already exists. 

The path prefix resides on a read-only file system. 

Path points outside the allocated address space of the process. 

The maximum number of links to the parent directory would be 
exceeded. 



[EIO] An I/O error has occurred while accessing the file system. 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is 
returned, and errno is set to indicate the error. 
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NAME 

mknod — make a directory, or a special or ordinary file 
SYNOPSIS 

int mknod (path, mode, dev) 
char *path; 
int mode, dev; 

DESCRIPTION 

mknod creates a new file named by the path name pointed to by path. The 
mode of the new file is initialized from mode. Where the value of mode is inter- 
preted as follows: 

0170000 file type; one of the following: 

0010000 fifo special 

0020000 character special 

0040000 directory ^ 

0060000 block special 
0100000 or 0000000 ordinary file 

0004000 set user ID on execution 

00020#0 set group ID on execution if # is 7, 5, 3, or 1 

enable mandatory file/record locking if # is 6, 4, 2, or 0 
0001000 save text image after execution 
0000777 access permissions; constructed from the following: 

0000400 read by owner 
0000200 write by owner 

0000100 execute (search on directory) by owner 
0000070 read, write, execute (search) by group 
0000007 read, write, execute (search) by others 

The owner ID of the file is set to the effective user ID of the process. The group 
ID of the file is set to the effective group ID of the process. 

Values of mode other than those above are undefined and should not be used. 
The low-order 9 bits of mode are modified by the process's file mode creation 
mask: all bits set in the process's file mode creation mask are cleared [see 
umask( 2)]. If mode indicates a block or character special file, dev is a 
configuration-dependent specification of a character or block I/O device. If 
mode does not indicate a block special or character special device, dev is ignored. 

mknod may be invoked only by the super-user for file types other than FIFO spe- 
cial. 

mknod will fail and the new file will not be created if one or more of the fol- 
lowing are true: 

[EPERM] The effective user ID of the process is not super-user. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] A component of the path prefix does not exist. 
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[EROFS] 


The directory in which the file is to be created is located on a 
read-only file system. 


[EEXIST] 


The named file exists. 


[EFAULT] 


Path points outside the allocated address space of the process. 


[ENOSPC] 


No space is available. 


[EINTR] 


A signal was caught during the mknod system call. 


[ENOLINK] 


Path points to a remote machine and the link to that machine is 
no longer active. 


[EMULTIHOP] 


Components of path require hopping to multiple remote 
machines. 



SEE ALSO 

chmod(2), exec(2), umask(2), fs(4). 
mkdir(l) in the User's Reference Manual. 

DIAGNOSTICS 

Upon successful completion a value of 0 is returned. Otherwise, a value of — 1 
is returned and errno is set to indicate the error. 

WARNING 

If mknod is used to create a device in a remote directory (Remote File Sharing), 
the major and minor device numbers are interpreted by the server. 
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NAME 

mount — mount a file system 



SYNOPSIS 

#include <sys/mount.h> 

int mount (spec, dir, mflag, fstyp) 
char *spec, *dir; 
int mflag, fstyp; 



DESCRIPTION 

mount requests that a removable file system contained on the block special file 
identified by spec be mounted on the directory identified by dir. Spec and dir 
are pointers to path names. Fstyp is the file system type number. The sysfs( 2) 
system call can be used to determine the file system type number. Note that if 
the MS_FSS flag bit of mflag is off, the file system type will default to the root 
file system type. Only if the bit is on will fstyp be used to indicate the file 
system type. 

Upon successful completion, references to the file dir will refer to the root direc- 
tory on the mounted file system. 

The low-order bit of mflag is used to control write permission on the mounted 
file system; if 1, writing is forbidden, otherwise writing is permitted according to 
individual file accessibility. 

mount may be invoked only by the super-user. It is intended for use only by 
the mount( 1M) utility. 

mount will fail if one or more of the following are true: 



[EPERM] 

[ENOENT] 

[ENOTDIR] 

[EREMOTE] 

[ENOLINK] 

[EMULTIHOP] 



The effective user ID is not super-user. 

Any of the named files does not exist. 

A component of a path prefix is not a directory. 

Spec is remote and cannot be mounted. 

Path points to a remote machine and the link to that machine is 
no longer active. 

Components of path require hopping to multiple remote 
machines. 



[ENOTBLK] 

[ENXIO] 

[ENOTDIR] 

[EFAULT] 

[EBUSY] 

[EBUSY] 

[EBUSY] 



Spec is not a block special device. 

The device associated with spec does not exist. 

Dir is not a directory. 

Spec or dir points outside the allocated address space of the 
process. 

Dir is currently mounted on, is someone's current working 
directory, or is otherwise busy. 

The device associated with spec is currently mounted. 

There are no more mount table entries. 



174 




MOUNT(2) 



MOUNT(2) 



[EROFS] Spec is write protected and mflag requests write permission. 

[ENOSPC] The file system state in the super-block is not FsOKAY and mflag 

requests write permission. 

[EINVAL] The super block has an invalid magic number or the fstyp is 

invalid or mflag is not valid. 

SEE ALSO 

sysfs(2), umount(2), fs(4). 

mount(lM) in the System Administrator's Reference Manual. 

DIAGNOSTICS 

Upon successful completion a value of 0 is returned. Otherwise, a value of —1 
is returned and errno is set to indicate the error. 
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NAME 

msgctl — message control operations 
SYNOPSIS 

#include <sys/types.h> 

#inciude <sys/ipc.h> 

#include <sys/msg.h> 

int msgctl (msqid, cmd, buf) 
int msqid, cmd; 
struct msqid ds *buf; 



DESCRIPTION 

msgctl provides a variety of message control operations as specified by cmd. The 
following cmds are available: 

IPC STAT Place the current value of each member of the data structure 
associated with msqid into the structure pointed to by buf. The 
contents of this structure are defined in intro( 2). {READ} 



IPCSET 



IPCRMID 



Set the value of the following members of the data structure 
associated with msqid to the corresponding value found in the 
structure pointed to by buf: 
msg_p er m.uid 
msgjDerm.gid 

msgjDerm.mode /* only low 9 bits */ 
msg_qbytes 

This cmd can only be executed by a process that has an effective 
user ID equal to either that of super user, or to the value of 
msgjperm.cuid or msgjperm.uid in the data structure associ- 
ated with msqid. Only super user can raise the value of 

msgqbytes. 

Remove the message queue identifier specified by msqid from 
the system and destroy the message queue and data structure 
associated with it. This cmd can only be executed by a process 
that has an effective user ID equal to either that of super user, 
or to the value of msgjperm.cuid or msgjperm.uid in the data 
structure associated with msqid. 



msgctl will fail if one or more of the following are true: 

[EINVAL] Msqid is not a valid message queue identifier. 

[EINVAL] Cmd is not a valid command. 

[EACCES] Cmd is equal to IPC STAT and {READ} operation permission is 

denied to the calling process [see intro (2)]. 

[EPERM] Cmd is equal to IPC_RMID or IPC_SET. The effective user ID of 

the calling process is not equal to that of super user, or to the 
value of msgjperm.cuid or msgjperm.uid in the data structure 
associated with msqid. 
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[EPERM] Cmd is equal to IPCSET, an attempt is being made to increase 

to the value of msg qbytes, and the effective user ID of the cal- 
ling process is not equal to that of super user. 

[EFAULT] Buf points to an illegal address. 

SEE ALSO 

intro(2), msgget(2), msgop(2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is 
returned and errno is set to indicate the error. 
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NAME 

msgget — get message queue 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

#include <sys/msg.h> 

int msgget (key, msgflg) 
key t key; 
int msgflg; 

DESCRIPTION 

msgget returns the message queue identifier associated with key. 

A message queue identifier and associated message queue and data structure [see 
intro ( 2)] are created for key if one of the following are true: 

Key is equal to IPC_PRIVATE. 

Key does not already have a message queue identifier associated with it, 
and ( msgflg & IPC_CREAT) is "true". 

Upon creation, the data structure associated with the new message queue 
identifier is initialized as follows: 



Msg_perm.cuid, msgjperm.uid, msg^perm.cgid, and msg_perm.gid are 
set equal to the effective user ID and effective group ID, respectively, of 
the calling process. 

The low-order 9 bits of msg_perm.mode are set equal to the low-order 9 
bits of msgflg. 

Msg qnum, msg_lspid, msg lrpid, msg stime, and msg rtime are set 
equal to 0. 

Msg ctime is set equal to the current time. 

Msg qbytes is set equal to the system limit. 

msgget will fail if one or more of the following are true: 

[EACCES] A message queue identifier exists for key, but operation permis- 

sion [see intro( 2)] as specified by the low-order 9 bits of msgflg 
would not be granted. 

[ENOENT] A message queue identifier does not exist for key and ( msgflg & 

IPCCREAT) is "false". 

[ENOSPC] A message queue identifier is to be created but the system- 

imposed limit on the maximum number of allowed message 
queue identifiers system wide would be exceeded. 

[EEXIST] A message queue identifier exists for key but (( msgflg & 

IPC CREAT) & ( msgflg & IPCEXCL)) is "true". 



SEE ALSO 

intro(2), msgctl(2), msgop(2). 
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DIAGNOSTICS 

Upon successful completion, a non-negative integer, namely a message queue 
identifier, is returned. Otherwise, a value of —1 is returned and errno is set to 
indicate the error. 
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NAME 

msgop — message operations 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

#include <sys/msg.h> 

int msgsnd (msqid, msgp, msgsz, msgflg) 
int msqid; 

struct msgbuf *msgp; 
int msgsz, msgflg; 

int msgrcv (msqid, msgp, msgsz, msgtyp, msgflg) 
int msqid; 

struct msgbuf *msgp; 
int msgsz; 
long msgtyp; 
int msgflg; 

DESCRIPTION 

Msgsnd is used to send a message to the queue associated with the message 
queue identifier specified by msqid. {WRITE} Msgp points to a structure con- 
taining the message. This structure is composed of the following members: 

long mtype; /* message type */ 

char mtext[]; /* message text */ 

Mtype is a positive integer that can be used by the receiving process for message 
selection (see msgrcv below). Mtext is any text of length msgsz bytes. Msgsz can 
range from 0 to a system-imposed maximum. 

Msgflg specifies the action to be taken if one or more of the following are true: 

The number of bytes already on the queue is equal to msg_qbytes [see 
intro( 2)]. 

The total number of messages on all queues system-wide is equal to the 
system-imposed limit. 

These actions are as follows: 

If ( msgflg & IPC NOWAIT) is "true", the message will not be sent and 
the calling process will return immediately. 

If ( msgflg & IPC NOWAIT) is "false", the calling process will suspend 
execution until one of the following occurs: 

The condition responsible for the suspension no longer exists, 
in which case the message is sent. 

Msqid is removed from the system [see msgctl( 2)]. When this 
occurs, errno is set equal to EIDRM, and a value of —1 is 
returned. 

The calling process receives a signal that is to be caught. In 
this case the message is not sent and the calling process 
resumes execution in the manner prescribed in signal( 2). 
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Msgsnd will fail and no message will be sent if one or more of the following are 
true: 

[EINVAL] Msqid is not a valid message queue identifier. 

[EACCES] Operation permission is denied to the calling process [see 

intro (2)]. 

[EINVAL] Mtype is less than 1. 

[EAGAIN] The message cannot be sent for one of the reasons cited above 

and ( msgflg & IPC_NOWAIT) is "true''. 

[EINVAL] Msgsz is less than zero or greater than the system-imposed limit. 

[EFAULT] Msgp points to an illegal address. 

Upon successful completion, the following actions are taken with respect to the 
data structure associated with msqid [see intro (2)]. 

Msg_qnum is incremented by 1 . 

Msg_lspid is set equal to the process ID of the calling process. 

Msg_stime is set equal to the current time. 

Msgrcv reads a message from the queue associated with the message queue 
identifier specified by msqid and places it in the structure pointed to by msgp. 
{READ} This structure is composed of the following members: 

long mtype; /* message type */ 

char mtextf]; /* message text */ 

Mtype is the received message's type as specified by the sending process. Mtext 
is the text of the message. Msgsz specifies the size in bytes of mtext. The 
received message is truncated to msgsz bytes if it is larger than msgsz and (msgflg 
& MSGNOERROR) is "true". The truncated part of the message is lost and no 
indication of the truncation is given to the calling process. 

Msgtyp specifies the type of message requested as follows: 

If msgtyp is equal to 0, the first message on the queue is received. 

If msgtyp is greater than 0, the first message of type msgtyp is received. 

If msgtyp is less than 0, the first message of the lowest type that is less 
than or equal to the absolute value of msgtyp is received. 

Msgflg specifies the action to be taken if a message of the desired type is not on 
the queue. These are as follows: 

If ( msgflg & IPCNOWAIT) is "true", the calling process will return 
immediately with a return value of —1 and errno set to ENOMSG. 

If (msgflg & IPC NOWAIT) is "false", the calling process will suspend 
execution until one of the following occurs: 

A message of the desired type is placed on the queue. 

Msqid is removed from the system. When this occurs, errno is 
set equal to EIDRM, and a value of —1 is returned. 
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The calling process receives a signal that is to be caught. In 
this case a message is not received and the calling process 
resumes execution in the manner prescribed in signal^ 2). 

Msgrcv will fail and no message will be received if one or more of the following 
are true: 



[EINVAL] 

[EACCES] 

[EINVALJ 

[E2BIG] 



Msqid is not a valid message queue identifier. 

Operation permission is denied to the calling process. 

Msgsz is less than 0. 

Mtext is greater than msgsz and ( msgflg & MSG NOERROR) is 
"false". 



[ENOMSG] The queue does not contain a message of the desired type and 
(msgtyp & IPC NOWAIT) is "true". 

[EFAULT] Msgp points to an illegal address. 

Upon successful completion, the following actions are taken with respect to the 
data structure associated with msqid [see intro (2)]. 

Msg qnum is decremented by 1 . 

Msg lrpid is set equal to the process ID of the calling process. 

Msg rtime is set equal to the current time. 

SEE ALSO 

intro(2), msgctl(2), msgget(2), signal(2). 

DIAGNOSTICS 

If msgsnd or msgrcv return due to the receipt of a signal, a value of —1 is 
returned to the calling process and errno is set to EINTR. If they return due to 
removal of msqid from the system, a value of —1 is returned and errno is set to 
EIDRM. 



Upon successful completion, the return value is as follows: 

Msgsnd returns a value of 0. 

Msgrcv returns a value equal to the number of bytes actually placed into 
mtext. 

Otherwise, a value of —1 is returned and errno is set to indicate the error. 
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NAME 

nice — change priority of a process 

SYNOPSIS 

int nice (incr) 
int incr; 

DESCRIPTION 

nice adds the value of incr to the nice value of the calling process. A process's 
nice value is a non-negative number for which a more positive value results in 
lower CPU priority. 

A maximum nice value of 39 and a minimum nice value of 0 are imposed by the 
system. (The default nice value is 20.) Requests for values above or below these 
limits result in the nice value being set to the corresponding limit. 

[EPERM] nice will fail and not change the nice value if incr is negative or 

greater than 39 and the effective user ID of the calling process is 
not super-user. 

SEE ALSO 

exec(2). 

nice(l) in the User's Reference Manual. 

DIAGNOSTICS 

Upon successful completion, nice returns the new nice value minus 20. Other- 
wise, a value of —1 is returned and errno is set to indicate the error. 



183 




OPEN(2) 



OPEN(2) 



NAME 

open — open for reading or writing 
SYNOPSIS 

#include <fciltl.h> 

int open (path, oflag [, mode] ) 

char *path; 

int oflag, mode; 

DESCRIPTION 

Path points to a path name naming a file, open opens a file descriptor for the 
named file and sets the file status flags according to the value of oflag. For non- 
STREAMS [see intro( 2)] files, oflag values are constructed by or-ing flags from the 
following list (only one of the first three flags below may be used): 

ORDONLY Open for reading only. 

O WRONLY Open for writing only. 

ORDWR Open for reading and writing. 

O^NDELAY This flag may affect subsequent reads and writes [see read( 2) and 
write( 2)]. 

When opening a FIFO with O RDONLY or O JVRONLY set: 

If 0_NDELAY is set: 

An open for reading-only will return without delay. An 
open for writing-only will return an error if no process 
currently has the file open for reading. 

If 0_NDELAY is clear: 

An open for reading-only will block until a process opens 
the file for writing. An open for writing-only will block 
until a process opens the file for reading. 

When opening a file associated with a communication line: 

If ONDELAY is set: 

The open will return without waiting for carrier. 

If O NDELAY is clear: 

The open will block until carrier is present. 

0_APPEND If set, the file pointer will be set to the end of the file prior to 
each write. 

O SYNC When opening a regular file, this flag affects subsequent writes. 

If set, each write ( 2) will wait for both the file data and file status 
to be physically updated. 

O CREAT If the file exists, this flag has no effect. Otherwise, the owner ID 
of the file is set to the effective user ID of the process, the group 
ID of the file is set to the effective group ID of the process, and 
the low-order 12 bits of the file mode are set to the value of 
mode modified as follows [see creat( 2)]: 
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All bits set in the file mode creation mask of the process 
are cleared [see umask( 2)]. 

The "save text image after execution bit" of the mode is 
cleared [see chmod( 2)]. 

O TRUNC If the file exists, its length is truncated to 0 and the mode and 
owner are unchanged. 

O EXCL If O EXCL and OCREAT are set, open will fail if the file exists. 

When opening a STREAMS file, oflag may be constructed from ONDELAY or-ed 
with either O RDONLY, OWRONLY or O RDWR. Other flag values are not appli- 
cable to STREAMS devices and have no effect on them. The value of O NDELAY 
affects the operation of STREAMS drivers and certain system calls [see read( 2), 
getmsg( 2), putmsg{ 2) and write( 2)]. For drivers, the implementation of O NDELAY 
is device-specific. Each STREAMS device driver may treat this option differently. 

Certain flag values can be set following open as described in fcntl( 2). 

The file pointer used to mark the current position within the file is set to the 
beginning of the file. 

The new file descriptor is set to remain open across exec system calls [see 
fcntl( 2)]. 

The named file is opened unless one or more of the following are true: 

[EACCES] A component of the path prefix denies search permission. 

[EACCES] oflag permission is denied for the named file. 

[E AG AIN] The file exists, mandatory file/record locking is set, and there 

are outstanding record locks on the file [see chmod (2)]. 

[EEXIST] 0_CREAT and O EXCL are set, and the named file exists. 

[EFAULT] Path points outside the allocated address space of the process. 

[EINTR] A signal was caught during the open system call. 

[EIO] A hangup or error occurred during a STREAMS open . 

[EISDIR] The named file is a directory and oflag is write or read/write. 

[EMFILE] NOFILES file descriptors are currently open. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

[ENFILE] The system file table is full. 

[ENOENT] O CREAT is not set and the named file does not exist. 

[ENOLINK] Path points to a remote machine, and the link to that machine 

is no longer active. 

[ENOMEM] The system is unable to allocate a send descriptor. 

[ENOSPC] O CREAT and 0_EXCL are set, and the file system is out of 

inodes. 

[ENOSR] Unable to allocate a stream. 
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[ENOTDIR] 

[ENXIO] 

[ENXIO] 

[ENXIO] 

[EROFS] 

[ETXTBSY] 

[EINTR] 

[ENOMEM] 

[ENOLINK] 

[EMULTIHOP] 



A component of the path prefix is not a directory. 

The named file is a character special or block special file, and 
the device associated with this special file does not exist. 

O NDELAY is set, the named file is a FIFO, 0_WR0NLY is set, 
and no process has the file open for reading. 

A STREAMS module or driver open routine failed. 

The named file resides on a read-only file system and oflag is 
write or read/write. 

The file is a pure procedure (shared text) file that is being exe- 
cuted and oflag is write or read/write. 

A signal was caught during the open system call. 

The system is unable to allocate a send descriptor. 

Path points to a remote machine, and the link to that machine 
is no longer active. 

Components of path require hopping to multiple remote 
machines. 



SEE ALSO 

chmod(2), close(2), creat(2), dup(2), fcntl(2), intro(2), lseek(2), read(2), getmsg(2), 
putmsg(2), umask(2), write(2). 

DIAGNOSTICS 

Upon successful completion, the file descriptor is returned. Otherwise, a value 
of —1 is returned and errno is set to indicate the error. 
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NAME 

pause — suspend process until signal 

SYNOPSIS 

pause () 

DESCRIPTION 

pause suspends the calling process until it receives a signal. The signal must be 
one that is not currently set to be ignored by the calling process. 

If the signal causes termination of the calling process, pause will not return. 

If the signal is caught by the calling process and control is returned from the 
signal-catching function [see signal (2)], the calling process resumes execution 
from the point of suspension; with a return value of —1 from pause and errno set 
to EINTR. 

SEE ALSO 

alarm(2), kill(2), signal(2), sigpause(2), wait(2). 



187 




PIPE(2) 



PIPE(2) 



NAME 

pipe — create an interprocess channel 

SYNOPSIS 

int pipe (fildes) 
int fildes[2]; 

DESCRIPTION 

pipe creates an I/O mechanism called a pipe and returns two file descriptors, 
fildes[0] and fildes[l]. Fildes[ 0] is opened for reading and fildes[l] is opened for 
writing. 

Up to 5120 bytes of data are buffered by the pipe before the writing process is 
blocked. A read only file descriptor fildes[0] accesses the data written to fildes[\] 
on a first-in-first-out (FIFO) basis. 

pipe will fail if: 

[EMFILE] NOFILES file descriptors are currently open. 

[ENFILE] The system file table is full. 

SEE ALSO 

read(2), write(2). 

sh(l) in the User's Reference Manual. 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 
is returned and errno is set to indicate the error. 
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NAME 

plock — lock process, text, or data in memory 
SYNOPSIS 

#include <sys/lock.h> 

int plock (op) 
int op; 



DESCRIPTION 

plock allows the calling process to lock its text segment (text lock), its data seg- 
ment (data lock), or both its text and data segments (process lock) into memory. 
Locked segments are immune to all routine swapping, plock also allows these 
segments to be unlocked. The effective user ID of the calling process must be 
super-user to use this call. Op specifies the following: 



PROCLOCK - 
TXTLOCK - 
DATLOCK - 
UNLOCK - 



lock text and data segments into memory (process lock) 
lock text segment into memory (text lock) 
lock data segment into memory (data lock) 
remove locks 



plock will fail and not perform the requested operation if one or more of the fol- 
lowing are true: 

[EPERM] The effective user ID of the calling process is not super-user. 

[EINVAL] Op is equal to PROCLOCK and a process lock, a text lock, or a 

data lock already exists on the calling process. 

[EINVAL] Op is equal to TXTLOCK and a text lock, or a process lock 

already exists on the calling process. 

[EINVAL] Op is equal to DATLOCK and a data lock, or a process lock 

already exists on the calling process. 

[EINVAL] Op is equal to UNLOCK and no type of lock exists on the calling 

process. 

[E AG AIN] Not enough memory. 

SEE ALSO 

exec(2), exit(2), fork(2). 



DIAGNOSTICS 

Upon successful completion, a value of 0 is returned to the calling process. Oth- 
erwise, a value of —1 is returned and errno is set to indicate the error. 



189 




POLL(2) 



POLL(2) 



NAME 

poll — STREAMS input/output multiplexing 
SYNOPSIS 

#include <stropts.h> 

#include <poll.h> 

int poll(fds, nfds, timeout) 
struct pollfd fds[]; 
unsigned long nfds; 
int timeout; 

DESCRIPTION 

poll provides users with a mechanism for multiplexing input/output over a set of 
file descriptors that reference open streams [see intro( 2)]. poll identifies those 
streams on which a user can send or receive messages, or on which certain 
events have occurred. A user can receive messages using read( 2) or getmsg( 2) 
and can send messages using write( 2) and putmsg( 2). Certain ioctl{ 2) calls, such 
as IRECVFD and ISENDFD [see streamio{7)\, can also be used to receive and send 
messages. 

Fds specifies the file descriptors to be examined and the events of interest for 
each file descriptor. It is a pointer to an array with one element for each open 
file descriptor of interest. The array's elements are pollfd structures which con- 
tain the following members: 

int fd; /* file descriptor */ 

short events; /* requested events */ 

short re vents; /* returned events */ 

where fd specifies an open file descriptor and events and revents are bitmasks 
constructed by or-ing any combination of the following event flags: 

POLLIN A non-priority or file descriptor passing message (see I RECVFD) is 
present on the stream head read queue. This flag is set even if the 
message is of zero length. In revents , this flag is mutually exclusive 
with POLLPRI. 

POLLPRI A priority message is present on the stream head read queue. This 
flag is set even if the message is of zero length. In revents , this flag 
is mutually exclusive with POLLIN. 

POLLOUT The first downstream write queue in the stream is not full. Priority 
control messages can be sent (see putmsg) at any time. 

POLLERR An error message has arrived at the stream head. This flag is only 
valid in the revents bitmask; it is not used in the events field. 

POLLHUP A hangup has occurred on the stream. This event and POLLOUT 
are mutually exclusive; a stream can never be writable if a hangup 
has occurred. However, this event and POLLIN or POLLPRI are not 
mutually exclusive. This flag is only valid in the revents bitmask; it 
is not used in the events field. 
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POLLNVAL The specified fd value does not belong to an open stream. This flag 
is only valid in the revents field; it is not used in the events field. 

For each element of the array pointed to by fds, poll examines the given file 
descriptor for the event(s) specified in events. The number of file descriptors to 
be examined is specified by nfds. If nfds exceeds NOFILES, the system limit of 
open files [see ulimit( 2)], poll will fail. 

If the value fd is less than zero, events is ignored and revents is set to 0 in that 
entry on return from poll. 

The results of the poll query are stored in the revents field in the pollfd structure. 
Bits are set in the revents bitmask to indicate which of the requested events are 
true. If none are true, none of the specified bits is set in revents when the poll 
call returns. The event flags POLLHUP, POLLERR and POLLNVAL are always set 
in revents if the conditions they indicate are true; this occurs even though these 
flags were not present in events. 

If none of the defined events have occurred on any selected file descriptor, poll 
waits at least timeout msec for an event to occur on any of the selected file 
descriptors. On a computer where millisecond timing accuracy is not available, 
timeout is rounded up to the nearest legal value available on that system. If the 
value timeout is 0, poll returns immediately. If the value of timeout is -1, poll 
blocks until a requested event occurs or until the call is interrupted, poll is not 
affected by the 0_NDELAY flag. 

poll fails if one or more of the following are true: 

[EAGAIN] Allocation of internal data structures failed but request should be 
attempted again. 

[EFAULT] Some argument points outside the allocated address space. 

[EINTR] A signal was caught during the poll system call. 

[EINVAL] The argument nfds is less than zero, or nfds is greater than 
NOFILES. 

SEE ALSO 

intro(2), read(2), getmsg(2), putmsg(2), write(2). 
streamio(7) in the System Administrator's Reference Manual. 

STREAMS Primer. 

STREAMS Programmer's Guide. 

DIAGNOSTICS 

Upon successful completion, a non-negative value is returned. A positive value 
indicates the total number of file descriptors that has been selected (i.e., file 
descriptors for which the revents field is non-zero). A value of 0 indicates that 
the call timed out and no file descriptors have been selected. Upon failure, a 
value of -1 is returned and errno is set to indicate the error. 
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NAME 

profil — execution time profile 
SYNOPSIS 

void profil (buff, bufsiz, offset, scale) 
char *buff; 

int bufsiz, offset, scale; 

DESCRIPTION 

Buff points to an area of core whose length (in bytes) is given by bufsiz. After 
this call, the user's program counter (pc) is examined each clock tick. Then the 
value of offset is subtracted from it, and the remainder multiplied by scale. If the 
resulting number corresponds to an entry inside buff , that entry is incremented. 
An entry is defined as a series of bytes with length size of (short). 

The scale is interpreted as an unsigned, fixed-point fraction with binary point at 
the left: 0177777 (octal) gives a 1-1 mapping of pc's to entries in buff; 077777 
(octal) maps each pair of instruction entries together. 02(octal) maps all instruc- 
tions onto the beginning of buff (producing a non-interrupting core clock). 

Profiling is turned off by giving a scale of 0 or 1. It is rendered ineffective by 
giving a bufsiz of 0. Profiling is turned off when an exec is executed, but 
remains on in child and parent both after a fork. Profiling will be turned off if 
an update in buff would cause a memory fault. 

SEE ALSO 

prof(l), times(2), monitor(3C). 

DIAGNOSTICS 

Not defined. 
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NAME 

ptrace — process trace 
SYNOPSIS 

int ptrace (request, pid, addr, data); 
int request, pid, addr, data; 

DESCRIPTION 

ptrace provides a means by which a parent process may control the execution of 
a child process. Its primary use is for the implementation of breakpoint debug- 
ging [see sdb( 1)]. The child process behaves normally until it encounters a signal 
[see signal^ 2) for the list], at which time it enters a stopped state and its parent is 
notified via wait (2). When the child is in the stopped state, its parent can 
examine and modify its "core image" using ptrace. Also, the parent can cause 
the child either to terminate or continue, with the possibility of ignoring the 
signal that caused it to stop. 

The request argument determines the precise action to be taken by ptrace and is 
one of the following: 

0 This request must be issued by the child process if it is to be traced 
by its parent. It turns on the child's trace flag that stipulates that 
the child should be left in a stopped state upon receipt of a signal 
rather than the state specified by func [see signal( 2)]. The pid, 
addr, and data arguments are ignored, and a return value is not 
defined for this request. Peculiar results will ensue if the parent 
does not expect to trace the child. 

The remainder of the requests can only be used by the parent process. For each, 
pid is the process ID of the child. The child must be in a stopped state before 
these requests are made. 

1, 2 With these requests, the word at location addr in the address space 
of the child is returned to the parent process. If I and D space are 
separated, request 1 returns a word from I space, and request 2 
returns a word from D space. If I and D space are not separated, 
either request 1 or request 2 may be used with equal results. The 
data argument is ignored. These two requests will fail if addr is 
not the start address of a word, in which case a value of —1 is 
returned to the parent process and the parent's errno is set to EIO. 

3 With this request, the word at location addr in the child's USER 
area in the system's address space (see <sys/user.h>) is returned 
to the parent process. The data argument is ignored. This request 
will fail if addr is not the start address of a word or is outside the 
USER area, in which case a value of —1 is returned to the parent 
process and the parent's errno is set to EIO. 

4, 5 With these requests, the value given by the data argument is 
written into the address space of the child at location addr. If I 
and D space are separated, request 4 writes a word into I space, 
and request 5 writes a word into D space. If I and D space are not 
separated, either request 4 or request 5 may be used with equal 
results. Upon successful completion, the value written into the 
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address space of the child is returned to the parent. These two 
requests will fail if addr is not the start address of a word. Upon 
failure a value of —1 is returned to the parent process and the 
parent's errno is set to EIO. 

6 With this request, a few entries in the child's USER area can be 
written. Data gives the value that is to be written and addr is the 
location of the entry. The few entries that can be written are: 

the general registers 

the condition codes of the Processor Status Word. 

7 This request causes the child to resume execution. If the data argu- 
ment is 0, all pending signals including the one that caused the 
child to stop are canceled before it resumes execution. If the data 
argument is a valid signal number, the child resumes execution as 
if it had incurred that signal, and any other pending signals are 
canceled. The addr argument must be equal to 1 for this request. 
Upon successful completion, the value of data is returned to the 
parent. This request will fail if data is not 0 or a valid signal 
number, in which case a value of —1 is returned to the parent pro- 
cess and the parent's errno is set to EIO. 

8 This request causes the child to terminate with the same conse- 
quences as exit( 2). 

9 This request sets the trace bit in the Processor Status Word of the 
child and then executes the same steps as listed above for request 
7. The trace bit causes an interrupt upon completion of one 
machine instruction. This effectively allows single stepping of the 
child. 

To forestall possible fraud, ptrace inhibits the set-user-id facility on subsequent 
exec (2) calls. If a traced process calls exec, it will stop before executing the first 
instruction of the new image showing signal SIGTRAP. 

General Errors 

ptrace will in general fail if one or more of the following are true: 

[EIO] Request is an illegal number. 

[ESRCH] Pid identifies a child that does not exist or has not executed a 

ptrace with request 0. 



SEE ALSO 

sdb(l), exec(2), signal(2), wait(2). 
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NAME 

putmsg — send a message on a stream 
SYNOPSIS 

#include <stropts.h> 

int putmsg (fd, ctlptr, dataptr, flags) 
int fd; 

struct strbuf * ctlptr; 
struct strbuf * dataptr; 
int flags; 

DESCRIPTION 

putmsg creates a message [see intro( 2)] from user specified buffer(s) and sends 
the message to a STREAMS file. The message may contain either a data part, a 
control part or both. The data and control parts to be sent are distinguished by 
placement in separate buffers, as described below. The semantics of each part is 
defined by the STREAMS module that receives the message. 

fd specifies a file descriptor referencing an open stream, ctlptr and dataptr each 
point to a strbuf structure which contains the following members: 

int maxlen; /* not used */ 

int len; /* length of data */ 

char *buf; /* ptr to buffer */ 

ctlptr points to the structure describing the control part, if any, to be included in 
the message. The buf field in the strbuf structure points to the buffer where the 
control information resides, and the len field indicates the number of bytes to be 
sent. The maxlen field is not used in putmsg [see getmsg( 2)]. In a similar 
manner, dataptr specifies the data, if any, to be included in the message, flags 
may be set to the values 0 or RS_HIPRI and is used as described below. 

To send the data part of a message, dataptr must be non-NULL and the len field 
of dataptr must have a value of 0 or greater. To send the control part of a mes- 
sage, the corresponding values must be set for ctlptr. No data (control) part will 
be sent if either dataptr ( ctlptr ) is NULL or the len field of dataptr (ctlptr) is set to 
- 1 . 

If a control part is specified, and flags is set to RS HIPRI, a priority message is 
sent. If flags is set to 0, a non-priority message is sent. If no control part is 
specified, and flags is set to RS_HIPRI, putmsg fails and sets errno to EINVAL. If 
no control part and no data part are specified, and flags is set to 0, no message is 
sent, and 0 is returned. 

For non-priority messages, putmsg will block if the stream write queue is full due 
to internal flow control conditions. For priority messages, putmsg does not block 
on this condition. For non-priority messages, putmsg does not block when the 
write queue is full and ONDELAY is set. Instead, it fails and sets errno to 
E AG AIN. 

putmsg also blocks, unless prevented by lack of internal resources, waiting for 
the availability of message blocks in the stream , regardless of priority or whether 
0_NDELAY has been specified. No partial message is sent. 
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putmsg fails if one or more of the following are true: 

[EAGAIN] A non-priority message was specified, the O NDELAY flag is set 
and the stream write queue is full due to internal flow control 
conditions. 

[EAGAIN] Buffers could not be allocated for the message that was to be 
created. 

[EBADF] fd is not a valid file descriptor open for writing. 

[EFAULT] ctlptr or dataptr points outside the allocated address space. 

[EINTR] A signal was caught during the putmsg system call. 

[EINVAL] An undefined value was specified in flags, or flags is set to 
RS_HIPRI and no control part was supplied. 

[EINVAL] The stream referenced by fd is linked below a multiplexor. 
[ENOSTR] A stream is not associated with fd . 

[ENXIO] A hangup condition was generated downstream for the specified 

stream. 

[ERANGE] The size of the data part of the message does not fall within the 
range specified by the maximum and minimum packet sizes of the 
topmost stream module. This value is also returned if the control 
part of the message is larger than the maximum configured size of 
the control part of a message, or if the data part of a message is 
larger than the maximum configured size of the data part of a 
message. 

A putmsg also fails if a STREAMS error message had been processed by the 
stream head before the call to putmsg. The error returned is the value contained 
in the STREAMS error message. 

SEE ALSO 

intro(2), read(2), getmsg(2), poll(2), write(2). 

STREAMS Primer. 

STREAMS Programmer's Guide. 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is 
returned and errno is set to indicate the error. 
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NAME 

read — read from file 
SYNOPSIS 

int read (Hides, buf, nbyte) 
int Hides; 
char *buf; 
unsigned nbyte; 

DESCRIPTION 

Tildes is a file descriptor obtained from a creat( 2), open (2), dup(l), fcntl(2), or 
pipe (2) system call. 

read attempts to read nbyte bytes from the file associated with fildes into the 
buffer pointed to by buf. 

On devices capable of seeking, the read starts at a position in the file given by 
the file pointer associated with fildes. Upon return from read, the file pointer is 
incremented by the number of bytes actually read. 

Devices that are incapable of seeking always read from the current position. 
The value of a file pointer associated with such a file is undefined. 

Upon successful completion, read returns the number of bytes actually read and 
placed in the buffer; this number may be less than nbyte if the file is associated 
with a communication line [see ioctl( 2) and termio(7)], or if the number of bytes 
left in the file is less than nbyte bytes. A value of 0 is returned when an end- 
of-file has been reached. 

A read from a STREAMS [see intro( 2)] file can operate in three different modes: 
"byte-stream" mode, "message-nondiscard" mode, and "message-discard" mode. 
The default is byte-stream mode. This can be changed using the I SRDOPT ioctl 
request [see streamio{7)\, and can be tested with the I GRDOPT ioctl. In byte- 
stream mode, read will retrieve data from the stream until it has retrieved nbyte 
bytes, or until there is no more data to be retrieved. Byte-stream mode ignores 
message boundaries. 

In STREAMS message-nondiscard mode, read retrieves data until it has read nbyte 
bytes, or until it reaches a message boundary. If the read does not retrieve all 
the data in a message, the remaining data are replaced on the stream , and can be 
retrieved by the next read or getmsg( 2) call. Message-discard mode also retrieves 
data until it has retrieved nbyte bytes, or it reaches a message boundary. How- 
ever, unread data remaining in a message after the read returns are discarded, 
and are not available for a subsequent read or getmsg. 

When attempting to read from a regular file with mandatory file/record locking 
set [see chmod( 2)], and there is a blocking (i.e. owned by another process) write 
lock on the segment of the file to be read: 

If ONDELAY is set, the read will return a -1 and set errno to E AG AIN. 

If O NDELAY is clear, the read will sleep until the blocking record lock is 
removed. 

When attempting to read from an empty pipe (or FIFO): 
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If ONDELAY is set, the read will return a 0. 

If 0_NDELAY is clear, the read will block until data is written to the file 
or the file is no longer open for writing. 

When attempting to read a file associated with a tty that has no data currently 
available: 

If O NDELAY is set, the read will return a 0. 

If O NDELAY is clear, the read will block until data becomes available. 

When attempting to read a file associated with a stream that has no data 
currently available: 

If ONDELAY is set, the read will return a -1 and set errno to E AG AIN. 

If O NDELAY is clear, the read will block until data becomes available. 

When reading from a STREAMS file, handling of zero-byte messages is deter- 
mined by the current read mode setting. In byte-stream mode, read accepts data 
until it has read nbyte bytes, or until there is no more data to read, or until a 
zero-byte message block is encountered, read then returns the number of bytes 
read, and places the zero-byte message back on the stream to be retrieved by the 
next read or getmsg. In the two other modes, a zero-byte message returns a 
value of 0 and the message is removed from the stream. When a zero-byte mes- 
sage is read as the first message on a stream, a value of 0 is returned regardless 
of the read mode. 

A read from a STREAMS file can only process data messages. It cannot process 
any type of protocol message and will fail if a protocol message is encountered 
at the stream head. 



read will fail if one or more of the following are true: 

[E AG AIN] Mandatory file/record locking was set, ONDELAY was set, 

and there was a blocking record lock. 

[E AG AIN] Total amount of system memory available when reading via 

raw IO is temporarily insufficient. 

[EAGAIN] No message waiting to be read on a stream and O NDELAY flag 

set. 



[EBADF] 

[EBADMSG] 

[EDEADLK] 

[EFAULT] 

[EINTR] 

[EINVAL] 

[ENOLCK] 

[ENOLINK] 



Fildes is not a valid file descriptor open for reading. 

Message waiting to be read on a stream is not a data message. 

The read was going to go to sleep and cause a deadlock situa- 
tion to occur. 

Buf points outside the allocated address space. 

A signal was caught during the read system call. 

Attempted to read from a stream linked to a multiplexor. 

The system record lock table was full, so the read could not go 
to sleep until the blocking record lock was removed. 

Fildes is on a remote machine and the link to that machine is no 
longer active. 
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A read from a STREAMS file will also fail if an error message is received at the 
stream head. In this case, errno is set to the value returned in the error message. 
If a hangup occurs on the stream being read, read will continue to operate nor- 
mally until the stream head read queue is empty. Thereafter, it will return 0. 

SEE ALSO 

creat(2), dup(2), fcntl(2), ioctl(2),intro(2), open(2), pipe(2), getmsg(2). 
streamio(7), termio(7) in the System Administrator's Reference Manual. 

DIAGNOSTICS 

Upon successful completion a non-negative integer is returned indicating the 
number of bytes actually read. Otherwise, a —1 is returned and errno is set to 
indicate the error. 
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NAME 

rmdir — remove a directory 

SYNOPSIS 

int rmdir (path) 
char *path; 

DESCRIPTION 

rmdir removes the directory named by the path name pointed to by path . The 
directory must not have any entries other than V and 

The named directory is removed unless one or more of the following are true: 
[EINVAL] The current directory may not be removed. 

[EINVAL] The entry of a directory may not be removed. 

[EEXIST] The directory contains entries other than those for and 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named directory does not exist. 

[EACCES] Search permission is denied for a component of the path prefix. 

[EACCES] Write permission is denied on the directory containing the 

directory to be removed. 

[EBUSY] The directory to be removed is the mount point for a mounted 

file system. 

[EROFS] The directory entry to be removed is part of a read-only file 

system. 

[EFAULT] Path points outside the process's allocated address space. 

[EIO] An I/O error occurred while accessing the file system. 

[ENOLINK] Path points to a remote machine, and the link to that machine 
is no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 
is returned and errno is set to indicate the error. 

SEE ALSO 

mkdir(2). 

rmdir(l), rm(l), and mkdir(l) in the User's Reference Manual. 
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NAME 

semctl — semaphore control operations 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

#include <sys/sem.h> 

int semctl (semid, semnum, cmd, arg) 
int semid, cmd; 
int semnum; 
union semun { 
int val; 

struct semid ds *buf; 
ushort *array; 

} arg; 

DESCRIPTION 

semctl provides a variety of semaphore control operations as specified by cmd. 

The following cmds are executed with respect to the semaphore specified by 
semid and semnum: 

GETVAL Return the value of semval [see intro (2)]. {READ} 

SET VAL Set the value of semval to arg.val. {ALTER} When this cmd 
is successfully executed, the semadj value corresponding to 
the specified semaphore in all processes is cleared. 

GETPID Return the value of sempid. {READ} 

GETNCNT Return the value of semncnt. {READ} 

GETZCNT Return the value of semzcnt. {READ} 

The following cmds return and set, respectively, every semval in the set of sema- 
phores. 

GET ALL Place semvals into array pointed to by arg. array. {READ} 

SET ALL Set semvals according to the array pointed to by arg. array. 

{ALTER} When this cmd is successfully executed the semadj 
values corresponding to each specified semaphore in all 
processes are cleared. 

The following cmds are also available: 

IPC STAT Place the current value of each member of the data struc- 
ture associated with semid into the structure pointed to by 
arg.buf. The contents of this structure are defined in 
intro( 2). {READ} 

IPC SET Set the value of the following members of the data struc- 
ture associated with semid to the corresponding value 
found in the structure pointed to by arg.buf: 

semjperm.uid 

semjjerm.gid 

semj>erm.mode /* only low 9 bits */ 
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This cmd can only be executed by a process that has an 
effective user ID equal to either that of super-user, or to the 
value of sem_perm.cuid or sem_perm.uid in the data 
structure associated with semid. 

IPCRMID Remove the semaphore identifier specified by semid from 
the system and destroy the set of semaphores and data 
structure associated with it. This cmd can only be exe- 
cuted by a process that has an effective user ID equal to 
either that of super-user, or to the value of sem_perm.cmd 
or sem_perm.uid in the data structure associated with 
semid. 

semctl fails if one or more of the following are true: 

[EINVAL] Semid is not a valid semaphore identifier. 

[EINVAL] Semnum is less than zero or greater than sem_nsems. 

[EINVAL] Cmd is not a valid command. 

[EACCES] Operation permission is denied to the calling process 

[see intro ( 2)]. 

[ERANGE] Cmd is SETVAL or SETALL and the value to which 

semval is to be set is greater than the system imposed 
maximum. 

[EPERM] Cmd is equal to IPC RMID or IPC SET and the effective 

user ID of the calling process is not equal to that of 
super-user, or to the value of semjperm.cuid or 
semj^erm.uid in the data structure associated with 
semid. 

[EFAULT] Arg.buf points to an illegal address. 

SEE ALSO 

intro(2), semget(2), semop(2). 

DIAGNOSTICS 

Upon successful completion, the value returned depends on cmd as follows: 

GETVAL The value of semval. 

GETPID The value of sempid. 

GETNCNT The value of semncnt. 

GETZCNT The value of semzcnt. 

All others A value of 0. 

Otherwise, a value of —1 is returned and errno is set to indicate the error. 
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NAME 

semget — get set of semaphores 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

#include <sys/sem.h> 

int semget (key, nsems, semflg) 

key t key; 

int nsems, semflg; 

DESCRIPTION 

semget returns the semaphore identifier associated with key. 

A semaphore identifier and associated data structure and set containing nsems 
semaphores [see intro( 2)] are created for key if one of the following is true: 

Key is equal to IPC_PRIVATE. 

Key does not already have a semaphore identifier associated with it, and 
(semflg & IPCCREAT) is "true". 

Upon creation, the data structure associated with the new semaphore identifier is 
initialized as follows: 

Sem_perm.cuid, sem_perm.uid, semjperm.cgid, and semjperm.gid are 

set equal to the effective user ID and effective group ID, respectively, of 
the calling process. 

The low-order 9 bits of sem^perm.mode are set equal to the low-order 9 
bits of semflg. 

Sem_nsems is set equal to the value of nsems. 

Sem otime is set equal to 0 and sem_ctime is set equal to the current 
time. 



semget fails if one or more of the following are true: 



[EINVAL] 

[EACCES] 

[EINVAL] 

[ENOENT] 

[ENOSPC] 



Nsems is either less than or equal to zero or greater than the 
system-imposed limit. 

A semaphore identifier exists for key, but operation permission 
[see intro (2)] as specified by the low-order 9 bits of semflg would 
not be granted. 

A semaphore identifier exists for key, but the number of sema- 
phores in the set associated with it is less than nsems, and nsems 
is not equal to zero. 

A semaphore identifier does not exist for key and (semflg & 
IPC CREAT) is "false". 

A semaphore identifier is to be created but the system-imposed 
limit on the maximum number of allowed semaphore identifiers 
system wide would be exceeded. 
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[ENOSPC] A semaphore identifier is to be created but the system-imposed 

limit on the maximum number of allowed semaphores system 
wide would be exceeded. 

[EEXIST] A semaphore identifier exists for key but ((semflg & IPC CREAT) 

and (semflg & IPC_EXCL)) is "true". 



SEE ALSO 

intro(2), semctl(2), semop(2). 

DIAGNOSTICS 

Upon successful completion, a non-negative integer, namely a semaphore 
identifier, is returned. Otherwise, a value of —1 is returned and errno is set to 
indicate the error. 
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NAME 

semop — semaphore operations 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

#include <sys/sem.h> 

int semop (semid, sops, nsops) 
int semid; 

struct sembuf **sops; 
unsigned nsops; 

DESCRIPTION 

semop is used to automatically perform an array of semaphore operations on the 
set of semaphores associated with the semaphore identifier specified by semid. 
Sops is a pointer to the array of semaphore-operation structures. Nsops is the 
number of such structures in the array. The contents of each structure includes 
the following members: 

short sem_num; /* semaphore number */ 

short sem_op; /* semaphore operation */ 

short sem flg; /* operation flags */ 

Each semaphore operation specified by sem_op is performed on the 
corresponding semaphore specified by semid and semjium. 

Sem_op specifies one of three semaphore operations as follows: 

If sem_op is a negative integer, one of the following will occur: {ALTER} 

If semval [see intro ( 2)] is greater than or equal to the absolute 
value of sem_op, the absolute value of sem_op is subtracted from 
semval. Also, if ( semjlg & SEM UNDO) is "true", the absolute 
value of sem_op is added to the calling process's semadj value 
[see exit( 2)] for the specified semaphore. 

If semval is less than the absolute value of s em_op and ( semjlg 
& IPCNOWAIT) is "true", semop will return immediately. 

If semval is less than the absolute value of sem_op and (semjlg 
& IPC NOWAIT) is "false", semop will increment the semncnt 
associated with the specified semaphore and suspend execution 
of the calling process until one of the following conditions 
occur. 

Semval becomes greater than or equal to the absolute value of 
sem_op. When this occurs, the value of semncnt associated 
with the specified semaphore is decremented, the absolute 
value of sem_op is subtracted from semval and, if ( semjlg & 
SEM UNDO) is "true", the absolute value of sem_op is added to 
the calling process's semadj value for the specified semaphore. 

The semid for which the calling process is awaiting action is 
removed from the system [see semctl( 2)]. When this occurs, 
errno is set equal to EIDRM, and a value of —1 is returned. 
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The calling process receives a signal that is to be caught. 
When this occurs, the value of semncnt associated with the 
specified semaphore is decremented, and the calling process 
resumes execution in the manner prescribed in signal( 2). 

If sem_op is a positive integer, the value of sem_op is added to semval 
and, if ( semjlg & SEM UNDO) is "true", the value of sem_op is sub- 
tracted from the calling process's semadj value for the specified sema- 
phore. {ALTER} 

If sem_op is zero, one of the following will occur: {READ} 

If semval is zero, semop will return immediately. 

If semval is not equal to zero and (semjlg & IPC NOWAIT) is 
"true", semop will return immediately. 

If semval is not equal to zero and (semjlg & IPC NOWAIT) is 
"false", semop will increment the semzcnt associated with the 
specified semaphore and suspend execution of the calling pro- 
cess until one of the following occurs: 

Semval becomes zero, at which time the value of semzcnt 
associated with the specified semaphore is decremented. 

The semid for which the calling process is awaiting action is 
removed from the system. When this occurs, errno is set equal 
to EIDRM, and a value of —1 is returned. 



The calling process receives a signal that is to be caught. 
When this occurs, the value of semzcnt associated with the 
specified semaphore is decremented, and the calling process 
resumes execution in the manner prescribed in signal( 2). 

semop will fail if one or more of the following are true for any of the semaphore 
operations specified by sops : 



[EINVAL] 

[EFBIG] 

[E2BIG] 

[EACCES] 

[EAGAIN] 

[ENOSPC] 



Semid is not a valid semaphore identifier. 

Semjium is less than zero or greater than or equal to the 
number of semaphores in the set associated with semid. 

Nsops is greater than the system-imposed maximum. 



Operation permission is denied to the calling process [see 
intro( 2)] 



The operation would result in suspension of the calling process 
but (semjlg & IPC_NOWAIT) is "true". 



The limit on the number of individual processes requesting an 
SEM UNDO would be exceeded. 



[EINVAL] The number of individual semaphores for which the calling pro- 

cess requests a SEM UNDO would exceed the limit. 

[ERANGE] An operation would cause a semval to overflow the system- 

imposed limit. 
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[ERANGE] An operation would cause a semadj value to overflow the 

system-imposed limit. 

[EFAULT] Sops points to an illegal address. 

Upon successful completion, the value of sempid for each semaphore specified 
in the array pointed to by sops is set equal to the process ID of the calling pro- 
cess. 

SEE ALSO 

exec(2), exit(2), fork(2), intro(2), semctl(2), semget(2). 

DIAGNOSTICS 

If semop returns due to the receipt of a signal, a value of —1 is returned to the 
calling process and errno is set to EINTR. If it returns due to the removal of a 
semid from the system, a value of —1 is returned and errno is set to EIDRM. 

Upon successful completion, a value of zero is returned. Otherwise, a value of 
—1 is returned and errno is set to indicate the error. 
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NAME 

setpgrp — set process group ID 

SYNOPSIS 

int setpgrp () 

DESCRIPTION 

setpgrp sets the process group ID of the calling process to the process ID of the 
calling process and returns the new process group ID. 

SEE ALSO 

exec(2), fork(2), getpid(2), intro(2), kill(2), signal(2). 

DIAGNOSTICS 

setpgrp returns the value of the new process group ID. 
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NAME 

setuid, setgid — set user and group IDs 

SYNOPSIS 

int setuid (uid) 
int uid; 

int setgid (gid) 
int gid; 

DESCRIPTION 

setuid (setgid) is used to set the real user (group) ID and effective user (group) ID 
of the calling process. 

If the effective user ID of the calling process is super-user, the real user (group) 
ID and effective user (group) ID are set to uid (gid). 

If the effective user ID of the calling process is not super-user, but its real user 
(group) ID is equal to uid (gid), the effective user (group) ID is set to uid (gid). 

If the effective user ID of the calling process is not super-user, but the saved set- 
user (group) ID from exec( 2) is equal to uid (gid), the effective user (group) ID is 
set to uid (gid). 

setuid (setgid) will fail if the real user (group) ID of the calling process is not 
equal to uid (gid) and its effective user ID is not super-user. [EPERM] 

The uid is out of range. [EINVAL] 

SEE ALSO 

getuid(2), intro(2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 
is returned and errno is set to indicate the error. 
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NAME 

shmctl — shared memory control operations 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

#include <sys/shm.h> 

int shmctl (shmid, cmd, buf) 
int shmid, cmd; 
struct shmid ds *buf; 

DESCRIPTION 

shmctl provides a variety of shared memory control operations as specified by 
cmd. The following cmds are available: 

IPC_STAT Place the current value of each member of the data structure associ- 
ated with shmid into the structure pointed to by buf. The contents 
of this structure are defined in intro (2). {READ} 

IPC SET Set the value of the following members of the data structure associ- 
ated with shmid to the corresponding value found in the structure 
pointed to by buf : 

shmjperm.uid 

shmjserm.gid 

shm_perm.mode /* only low 9 bits */ 

This cmd can only be executed by a process that has an effective 
user ID equal to that of super user, or to the value of 
shmjperm.cuid or shm_perm.uid in the data structure associated 
with shmid. 

IPC_RMID Remove the shared memory identifier specified by shmid from the 
system and destroy the shared memory segment and data structure 
associated with it. This cmd can only be executed by a process that 
has an effective user ID equal to that of super user, or to the value 
of shm_perm.cuid or shmj>erm.uid in the data structure associ- 
ated with shmid. 

SHM LOCK Lock the shared memory segment specified by shmid in memory. 

This cmd can only be executed by a process that has an effective 
user ID equal to super user. 

SHMUNLOCK 

Unlock the shared memory segment specified by shmid. This cmd 
can only be executed by a process that has an effective user ID 
equal to super user. 

shmctl will fail if one or more of the following are true: 

[EINVAL] Shmid is not a valid shared memory identifier. 

[EINVAL] Cmd is not a valid command. 

[EACCES] Cmd is equal to IPC_STAT and {READ} operation permission is 
denied to the calling process [see intro ( 2)]. 
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[EPERM] Cmd is equal to IPC RMID or IPCSET and the effective user ID of 
the calling process is not equal to that of super user, or to the value 
of shmj?erm.cuid or shm_perm.uid in the data structure associ- 
ated with shmid. 

[EPERM] Cmd is equal to SHMLOCK or SHM UNLOCK and the effective user 
ID of the calling process is not equal to that of super user. 

[EFAULT] Buf points to an illegal address. 

[ENOMEM] Cmd is equal to SHM LOCK and there is not enough memory. 

SEE ALSO 

shmget(2), shmop(2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is 

returned and errno is set to indicate the error. 

NOTES 

The user must explicitly remove shared memory segments after the last reference 

to them has been removed. 
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NAME 

shmget — get shared memory segment identifier 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

#include <sys/shm.h> 

int shmget (key, size, shmflg) 

key t key; 

int size, shmflg; 

DESCRIPTION 

shmget returns the shared memory identifier associated with key. 

A shared memory identifier and associated data structure and shared memory 
segment of at least size bytes [see intro(2)\ are created for key if one of the fol- 
lowing are true: 

Key is equal to IPC_PRIVATE. 

Key does not already have a shared memory identifier associated with it, 
and (shmflg & IPC_CREAT) is "true". 

Upon creation, the data structure associated with the new shared memory 
identifier is initialized as follows: 

Shmj>erm.cuid, shmjperm.uid, shm_perm.cgid, and shm_perm.gid 

are set equal to the effective user ID and effective group ID, respectively, 
of the calling process. 

The low-order 9 bits of shmjperm.mode are set equal to the low-order 
9 bits of shmflg. Shmjsegsz is set equal to the value of size. 

Shm lpid, shm nattch, shm atime, and shm dtime are set equal to 0. 
Shm_ctime is set equal to the current time. 
shmget will fail if one or more of the following are true: 

[EINVAL] Size is less than the system-imposed minimum or greater than 

the system-imposed maximum. 

[EACCES] A shared memory identifier exists for key but operation permis- 

sion [see intro ( 2)] as specified by the low-order 9 bits of shmflg 
would not be granted. 

[EINVAL] A shared memory identifier exists for key but the size of the 

segment associated with it is less than size and size is not equal 
to zero. 

[ENOENT] A shared memory identifier does not exist for key and ( shmflg & 

IPC CREAT) is "false". 

[ENOSPC] A shared memory identifier is to be created but the system- 

imposed limit on the maximum number of allowed shared 
memory identifiers system wide would be exceeded. 
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[ENOMEM] A shared memory identifier and associated shared memory seg- 
ment are to be created but the amount of available memory is 
not sufficient to fill the request. 

[EEXIST] A shared memory identifier exists for key but (( shmflg & 

IPC CREAT) and ( shmflg& IPC_EXCL)) is "true". 

SEE ALSO 

intro(2), shmctl(2), shmop(2). 

DIAGNOSTICS 

Upon successful completion, a non-negative integer, namely a shared memory 
identifier is returned. Otherwise, a value of —1 is returned and errno is set to 
indicate the error. 

NOTES 

The user must explicitly remove shared memory segments after the last reference 
to them has been removed. 
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NAME 

shmop — shared memory operations 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

# include <sys/shm.h> 

char *shmat (shmid, shmaddr, shmflg) 
int shmid; 
char *shmaddr; 
int shmflg; 

int shmdt (shmaddr) 
char *shmaddr; 



DESCRIPTION 

Shmat attaches the shared memory segment associated with the shared memory 
identifier specified by shmid to the data segment of the calling process. The seg- 
ment is attached at the address specified by one of the following criteria: 

If shmaddr is equal to zero, the segment is attached at the first available 
address as selected by the system. 

If shmaddr is not equal to zero and ( shmflg & SHMRND) is "true", the 
segment is attached at the address given by (shmaddr - (shmaddr 
modulus SHMLBA)). 

If shmaddr is not equal to zero and (shmflg & SHM RND) is "false", the 
segment is attached at the address given by shmaddr . 

Shmdt detaches from the calling process's data segment the shared memory seg- 
ment located at the address specified by shmaddr. 

The segment is attached for reading if (shmflg & SHM RDONLY) is "true" 
{READ}, otherwise it is attached for reading and writing {READ/WRITE}. 

Shmat will fail and not attach the shared memory segment if one or more of the 
following are true: 



[EINVAL] 

[EACCES] 

[ENOMEM] 

[EINVAL] 

[EINVAL] 

[EMFILE] 

[EINVAL] 



Shmid is not a valid shared memory identifier. 

Operation permission is denied to the calling process [see 
intro (2)]. 

The available data space is not large enough to accommodate 
the shared memory segment. 

Shmaddr is not equal to zero, and the value of (shmaddr - 
(shmaddr modulus SHMLBA)) is an illegal address. 

Shmaddr is not equal to zero, (shmflg & SHM RND) is "false", 
and the value of shmaddr is an illegal address. 

The number of shared memory segments attached to the calling 
process would exceed the system-imposed limit. 

Shmdt will fail and not detach the shared memory segment if 
shmaddr is not the data segment start address of a shared 
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memory segment. 

SEE ALSO 

exec(2), exit(2), fork(2), intro(2), shmctl(2), shmget(2). 

DIAGNOSTICS 

Upon successful completion, the return value is as follows: 

Shmat returns the data segment start address of the attached shared 
memory segment. 

Shmdt returns a value of 0. 

Otherwise, a value of —1 is returned and errno is set to indicate the error. 



NOTES 



The user must explicitly remove shared memory segments after the last reference 
to them has been removed. 
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NAME 

signal — specify what to do upon receipt of a signal 
SYNOPSIS 

#include <signal.h> 

void (*signal (sig, func))() 

int sig; 

void (*func)(); 



DESCRIPTION 

signal allows the calling process to choose one of three ways in which it is pos- 
sible to handle the receipt of a specific signal. Sig specifies the signal and June 
specifies the choice. 

Sig can be assigned any one of the following except SIGKILL: 



SIGHUP 


01 


SIGINT 


02 


SIGQUIT 


03 [1] 


SIGILL 


04 [1] 


SIGTRAP 


05™ 


SIGIOT 


06™ 


SIGEMT 


O/m 


SIGFPE 


08™ 


SIGKILL 


09 


SIGBUS 


10™ 


SIGSEGV 


11™ 


SIGSYS 


i 2 m 


SIGPIPE 


13 


SIGALRM 


14 


SIGTERM 


15 


SIGUSR1 


16 


SIGUSR2 


17 


SIGCLD 


18™ 


SIGPWR 


19™ 


SIGPOLL 


22PI 



hangup 

interrupt 

quit 

illegal instruction (not reset when caught) 
trace trap (not reset when caught) 

IOT instruction 

EMT instruction 

floating point exception 

kill (cannot be caught or ignored) 

bus error 

segmentation violation 
bad argument to system call 
write on a pipe with no one to read it 
alarm clock 

software termination signal 
user-defined signal 1 
user-defined signal 2 
death of a child 
power fail 

selectable event pending 



Func is assigned one of three values: SIGDFL, SIG_IGN, or a function address. 
SIG DFL, and SIG IGN, are defined in the include file signal.h. Each is a macro 
that expands to a constant expression of type pointer to function returning void, 
and has a unique value that matches no declarable function. 

The actions prescribed by the values of func are as follows: 

SIG DFL — terminate process upon receipt of a signal 

Upon receipt of the signal sig, the receiving process is to be ter- 
minated with all of the consequences outlined in exit( 2). See NOTE 
[1] below. 

SIG IGN — ignore signal 

The signal sig is to be ignored. 

Note: the signal SIGKILL cannot be ignored. 
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function address — catch signal 

Upon receipt of the signal sig, the receiving process is to execute the 
signal-catching function pointed to by func. The signal number sig 
will be passed as the only argument to the signal-catching function. 
Additional arguments are passed to the signal-catching function for 
hardware-generated signals. Before entering the signal-catching func- 
tion, the value of func for the caught signal will be set to SIG DFL 
unless the signal is SIGILL, SIGTRAP, or SIGPWR. 

Upon return from the signal-catching function, the receiving process 
will resume execution at the point it was interrupted. 

When a signal that is to be caught occurs during a read( 2), a write (2), 
an open( 2), or an ioctl( 2) system call on a slow device (like a ter- 
minal; but not a file), during a pause ( 2) system call, or during a 
wait (2) system call that does not return immediately due to the 
existence of a previously stopped or zombie process, the signal 
catching function will be executed and then the interrupted system 
call may return a —1 to the calling process with errno set to EINTR. 

signal will not catch an invalid function argument, func, and results 
are undefined when an attempt is made to execute the function at the 
bad address. 

Note: The signal SIGKILL cannot be caught. 

A call to signal cancels a pending signal sig except for a pending SIGKILL signal. 
signal will fail if sig is an illegal signal number, including SIGKILL. [EINVAL] 

NOTES 

[1] If SIGJDFL is assigned for these signals, in addition to the process being ter- 
minated, a "core image" will be constructed in the current working directory 
of the process, if the following conditions are met: 

The effective user ID and the real user ID of the receiving process 
are equal. 

An ordinary file named core exists and is writable or can be 
created. If the file must be created, it will have the following pro- 
perties: 

a mode of 0666 modified by the file creation mask [see 
umask(2)\ 

a file owner ID that is the same as the effective user ID of 
the receiving process. 

a file group ID that is the same as the effective group ID of 
the receiving process 

[2] For the signals SIGCLD and SIGPWR, func is assigned one of three values: 
SIG DFL, SIG IGN, or a function address. The actions prescribed by these 
values are: 

SIG DFL - ignore signal 

The signal is to be ignored. 
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SIGIGN - ignore signal 

The signal is to be ignored. Also, if sig is SIGCLD, the calling 
process's child processes will not create zombie processes when 
they terminate [see exit( 2)]. 

function address - catch signal 

If the signal is SIGPWR, the action to be taken is the same as that 
described above for func equal to function address. The same is 
true if the signal is SIGCLD with one exception: while the process 
is executing the signal-catching function, any received SIGCLD 
signals will be ignored. (This is the default action.) 

In addition, SIGCLD affects the wait, and exit system calls as follows: 

wait If the func value of SIGCLD is set to SIG IGN and a wait is exe- 
cuted, the wait will block until all of the calling process's child 
processes terminate; it will then return a value of —1 with errno 
set to ECHILD. 

exit If in the exiting process's parent process the func value of 
SIGCLD is set to SIG IGN, the exiting process will not create a 
zombie process. 

When processing a pipeline, the shell makes the last process in the pipe- 
line the parent of the proceeding processes. A process that may be piped 
into in this manner (and thus become the parent of other processes) 
should take care not to set SIGCLD to be caught. 

[3] SIGPOLL is issued when a file descriptor corresponding to a STREAMS [see 
intro( 2)] file has a "selectable" event pending. A process must specifically 
request that this signal be sent using the I SETSIG ioctl call. Otherwise, the 
process will never receive SIGPOLL. 

SEE ALSO 

intro(2), kill(2), pause(2), ptrace(2), wait(2), setjmp(3C), sigset(2). 
kill(l) in the User's Reference Manual. 

DIAGNOSTICS 

Upon successful completion, signal returns the previous value of func for the 
specified signal sig. Otherwise, a value of SIGERR is returned and errno is set 
to indicate the error. SIG ERR is defined in the include file signal.h. 
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NAME 

sigset, sighold, sigrelse, sigignore, sigpause — signal management 
SYNOPSIS 

#include <signal.h> 

void (*sigset (sig, func))() 

int sig; 

void (*func)(); 

int sighold (sig) 
int sig; 

int sigrelse (sig) 
int sig; 

int sigignore (sig) 
int sig; 

int sigpause (sig) 
int sig; 

DESCRIPTION 

These functions provide signal management for application processes, sigset 
specifies the system signal action to be taken upon receipt of signal sig . This 
action is either calling a process signal-catching handler func or performing a 
system-defined action. 

Sig can be assigned any one of the following values except SIGKILL. Machine or 
implementation dependent signals are not included (see NOTES below). Each 
value of sig is a macro, defined in < signal. h> , that expands to an integer con- 



stant expression. 




SIGHUP 


hangup 


SIGINT 


interrupt 


SIGQUIT* 


quit 


SIGILL* 


illegal instruction (not held when caught) 


SIGTRAP* 


trace trap (not held when caught) 


SIGABRT* 


abort 


SIGFPE* 


floating point exception 


SIGKILL 


kill (can not be caught or ignored) 


SIGSYS* 


bad argument to system call 


SIGPIPE 


write on a pipe with no one to read it 


SIGALRM 


alarm clock 


SIGTERM 


software termination signal 


SIGUSR1 


user-defined signal 1 


SIGUSR2 


user-defined signal 2 


SIGCLD 


death of a child (see WARNING below) 


SIGPWR 


power fail (see WARNING below) 


SIGPOLL 


selectable event pending (see NOTES belo 



See below under SIG_DFL regarding asterisks (*) in the above list. 
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The following values for the system-defined actions of func are also defined in 
<signal.h > . Each is a macro that expands to a constant expression of type 
pointer to function returning void and has a unique value that matches no 
declarable function. 

SIGJDFL — default system action 

Upon receipt of the signal sig, the receiving process is to be ter- 
minated with all of the consequences outlined in exit( 2). In addition 
a "core image" will be made in the current working directory of the 
receiving process if sig is one for which an asterisk appears in the 
above list and the following conditions are met: 

The effective user ID and the real user ID of the receiving 
process are equal. 

An ordinary file named core exists and is writable or can be 
created. If the file must be created, it will have the fol- 
lowing properties: 

a mode of 0666 modified by the file creation mask 
[see umask( 2)] 

a file owner ID that is the same as the effective user 
ID of the receiving process. 

a file group ID that is the same as the effective 
group ID of the receiving process 

SIG IGN — ignore signal 

Any pending signal sig is discarded and the system signal action is set 
to ignore future occurrences of this signal type. 

SIG HOLD - hold signal 

The signal sig is to be held upon receipt. Any pending signal of this 
type remains held. Only one signal of each type is held. 

Otherwise, func must be a pointer to a function, the signal-catching handler, that 
is to be called when signal sig occurs. In this case, sigset specifies that the pro- 
cess will call this function upon receipt of signal sig. Any pending signal of this 
type is released. This handler address is retained across calls to the other signal 
management functions listed here. 

When a signal occurs, the signal number sig will be passed as the only argument 
to the signal-catching handler. Before calling the signal-catching handler, the 
system signal action will be set to SIG_HOLD . During normal return from the 
signal-catching handler, the system signal action is restored to func and any held 
signal of this type released. If a non-local goto ( longjmp ) is taken, then sigrelse 
must be called to restore the system signal action and release any held signal of 
this type. 

In general, upon return from the signal-catching handler, the receiving process 
will resume execution at the point it was interrupted. However, when a signal is 
caught during a read( 2), a write( 2), an open( 2), or an ioctl( 2) system call during a 
sigpause system call, or during a wait{ 2) system call that does not return immedi- 
ately due to the existence of a previously stopped or zombie process, the signal- 
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catching handler will be executed and then the interrupted system call may 
return a —1 to the calling process with errno set to EINTR. 

Sighold and sigrelse are used to establish critical regions of code. Sighold is 
analogous to raising the priority level and deferring or holding a signal until the 
priority is lowered by sigrelse. Sigrelse restores the system signal action to that 
specified previously by sigset. 

Sigignore sets the action for signal sig to SIGJGN (see above). 

Sigpause suspends the calling process until it receives a signal, the same as 
pause (2). However, if the signal sig had been received and held, it is released 
and the system signal action taken. This system call is useful for testing vari- 
ables that are changed on the occurrence of a signal. The correct usage is to use 
sighold to block the signal first, then test the variables. If they have not 
changed, then call sigpause to wait for the signal, sigset will fail if one or more 
of the following are true: 

[EINVAL] Sig is an illegal signal number (including SIGKILL) or the default 

handling of sig cannot be changed. 

[EINTR] A signal was caught during the system call sigpause. 

DIAGNOSTICS 

Upon successful completion, sigset returns the previous value of the system 
signal action for the specified signal sig. Otherwise, a value of SIG_ERR is 
returned and errno is set to indicate the error. SIG_ERR is defined in <signal.h> . 

For the other functions, upon successful completion, a value of 0 is returned. 
Otherwise, a value of —1 is returned and errno is set to indicate the error. 

SEE ALSO 

kill(2), pause(2), signal(2), wait(2), setjmp(3C). 

WARNING 

Two signals that behave differently than the signals described above exist in this 
release of the system: 

SIGCLD death of a child (reset when caught) 

SIGPWR power fail (not reset when caught) 

For these signals, func is assigned one of three values: SIGDFL, SIGJGN, or a 
function address. The actions prescribed by these values are as follows: 

SIG DFL - ignore signal 

The signal is to be ignored. 

SIGJGN - ignore signal 

The signal is to be ignored. Also, if sig is SIGCLD, the calling pro- 
cess's child processes will not create zombie processes when they ter- 
minate [see exit (2)]. 

function address - catch signal 

If the signal is SIGPWR, the action to be taken is the same as that 
described above for func equal to function address. The same is true 
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if the signal is SIGCLD with one exception: while the process is exe- 
cuting the signal-catching function, any received SIGCLD signals will 
be ignored. (This is the default action.) 

The SIGCLD affects two other system calls [wait( 2), and exit( 2)] in the fol- 
lowing ways: 

wait If the func value of SIGCLD is set to SIG IGN and a wait is executed, 
the wait will block until all of the calling process's child processes 
terminate; it will then return a value of —1 with errno set to ECHILD. 

exit If in the exiting process's parent process the func value of SIGCLD is 
set to SIG_IGN , the exiting process will not create a zombie process. 

When processing a pipeline, the shell makes the last process in the pipeline 
the parent of the proceeding processes. A process that may be piped into in 
this manner (and thus become the parent of other processes) should take care 
not to set SIGCLD to be caught. 

NOTES 

SIGPOLL is issued when a file descriptor corresponding to a STREAMS [see 
intro( 2)] file has a "selectable” event pending. A process must specifically request 
that this signal be sent using the I SETSIG ioctl( 2) call [see streamio(7)]. Other- 
wise, the process will never receive SIGPOLL. 

For portability, applications should use only the symbolic names of signals 
rather than their values and use only the set of signals defined here. The action 
for the signal SIGKILL can not be changed from the default system action. 

Specific implementations may have other implementation-defined signals. Also, 
additional implementation-defined arguments may be passed to the signal- 
catching handler for hardware-generated signals. For certain hardware- 
generated signals, it may not be possible to resume execution at the point of 
interruption. 

The signal type SIGSEGV is reserved for the condition that occurs on an invalid 
access to a data object. If an implementation can detect this condition, this 
signal type should be used. 

The other signal management functions, signal(2) and pause( 2), should not be 
used in conjunction with these routines for a particular signal type. 
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NAME 

stat, fstat — get file status 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/stat.h> 

int stat (path, buf) 
char *path; 
struct stat *buf; 

int fstat (tildes, buf) 
int hides; 
struct stat *buf; 

DESCRIPTION 

Path points to a path name naming a file. Read, write, or execute permission of 
the named file is not required, but all directories listed in the path name leading 
to the file must be searchable, stat obtains information about the named file. 

Note that in a Remote File Sharing environment, the information returned by 
stat depends upon the user/group mapping set up between the local and remote 
computers. [See idload( 1M)]. 

Fstat obtains information about an open file known by the file descriptor fildes, 
obtained from a successful open, creat, dup, fcntl, or pipe system call. 

Buf is a pointer to a stat structure into which information is placed concerning 
the file. 

The contents of the structure pointed to by buf include the following members: 
ushort stjnode; /* File mode [see mknod( 2)] */ 

ino_t st_ino; /* Inode number */ 

dev_t st_dev; /* ID of device containing */ 

/* a directory entry for this file * / 
dev_t st_rdev; /* ID of device */ 

/* This entry is defined only for */ 

/ * character special or block special files * / 
short st_nlink; /* Number of links * / 

ushort st uid; /* User ID of the file's owner */ 

ushort st_gid; /* Group ID of the file's group */ 

off_t st_size; /* File size in bytes */ 

time _t st_atime; /* Time of last access * / 

time_t st mtime; /* Time of last data modification */ 

time_t st_ctime; /* Time of last file status change */ 

/* Times measured in seconds since */ 

/* 00:00:00 GMT, Jan. 1, 1970 */ 

stjnode The mode of the file as described in the mknod( 2) system call. 

st_ino This field uniquely identifies the file in a given file system. The pair 
st_ino and st_dev uniquely identifies regular files. 

st_dev This field uniquely identifies the file system that contains the file. Its 
value may be used as input to the ustat( 2) system call to determine 
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more information about this file system. No other meaning is associ- 
ated with this value. 

st_rdev This field should be used only by administrative commands. It is 
valid only for block special or character special files and only has 
meaning on the system where the file was configured. 

st nlink This field should be used only by administrative commands. 

st uid The user ID of the file's owner. 

st_gid The group ID of the file's group. 

st size For regular files, this is the address of the end of the file. For pipes 
or fifos, this is the count of the data currently in the file. For block 
special or character special, this is not defined. 

st_atime Time when file data was last accessed. Changed by the following 
system calls: creat( 2), mknod( 2), pipe( 2), utime( 2), and read( 2). 

stjmtime Time when data was last modified. Changed by the following 
system calls: creat( 2), mknod( 2), pipe( 2), utime( 2), and write( 2). 

st_ctime Time when file status was last changed. Changed by the following 
system calls: chmod( 2), chown( 2), creat( 2), link( 2), mknod( 2), pipe( 2), 
unlink( 2), utime( 2), and write( 2). 

stat will fail if one or more of the following are true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied for a component of the path prefix. 

[EFAULT] Buf or path points to an invalid address. 

[EINTR] A signal was caught during the stat system call. 

[ENOLINK] Path points to a remote machine and the link to that machine is 
no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 

Fstat will fail if one or more of the following are true: 

[EBADF] Fildes is not a valid open file descriptor. 

[EFAULT] Buf points to an invalid address. 

[ENOLINK] Fildes points to a remote machine and the link to that machine 
is no longer active. 
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SEE ALSO 

chmod(2), chown(2), creat(2), link(2), mknod(2), pipe(2), read(2), time(2), 
unlink(2), utime(2), write(2). 

DIAGNOSTICS 

Upon successful completion a value of 0 is returned. Otherwise, a value of — 1 
is returned and errno is set to indicate the error. 
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NAME 

statfs, fstatfs — get file system information 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/statfs.h> 

int statfs (path, buf, len, fstyp) 
char *path; 
struct statfs *buf; 
int len, fstyp; 

int fstatfs (hides, buf, len, fstyp) 

int hides; 

struct statfs *buf; 

int len, fstyp; 

DESCRIPTION 

statfs returns a "generic superblock" describing a file system. It can be used to 
acquire information about mounted as well as unmounted file systems, and 
usage is slightly different in the two cases. In all cases, buf is a pointer to a 
structure (described below) which will be filled by the system call, and len is the 
number of bytes of information which the system should return in the structure. 
Len must be no greater than sizeof (struct statfs) and ordinarily it will contain 
exactly that value; if it holds a smaller value the system will fill the structure 
with that number of bytes. (This allows future versions of the system to grow 
the structure without invalidating older binary programs.) 

If the file system of interest is currently mounted, path should name a file which 
resides on that file system. In this case the file system type is known to the 
operating system and the fstyp argument must be zero. For an unmounted file 
system path must name the block special file containing it and fstyp must con- 
tain the (non-zero) file system type. In both cases read, write, or execute per- 
mission of the named file is not required, but all directories listed in the path 
name leading to the file must be searchable. 

The statfs structure pointed to by buf includes the following members: 



short 


f_fstyp; 


/* File system type */ 


short 


fjbsize; 


/* Block size */ 


short 


ffrsize; 


/* Fragment size */ 


long 


f_blocks; 


/* Total number of blocks */ 


long 


fjbfree; 


/* Count of free blocks */ 


long 


ffiles; 


/* Total number of file nodes */ 


long 


fffree; 


/* Count of free file nodes */ 


char 


f_fname[6]; 


/* Volume name */ 


char 


f_fpack[6]; 


/* Pack name */ 



fstatfs is similar, except that the file named by path in statfs is instead identified 
by an open file descriptor filedes obtained from a successful open( 2), creat( 2), 
dup(2), fcntl{2), or pipe( 2) system call. 

statfs obsoletes ustat( 2) and should be used in preference to it in new programs. 
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statfs and fstatfs will fail if one or more of the following are true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied for a component of the path prefix. 

[EFAULT] Buf or path points to an invalid address. 

[EBADF] Tildes is not a valid open file descriptor. 

[EINVAL] Fstyp is an invalid file system type; path is not a block special 

file and fstyp is nonzero; len is negative or is greater than sizeof 
(struct statfs). 

[ENOLINK] Path points to a remote machine, and the link to that machine 
is no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 



DIAGNOSTICS 

Upon successful completion a value of 0 is returned. Otherwise, a value of — 1 
is returned and errno is set to indicate the error. 

SEE ALSO 

chmod(2), chown(2), creat(2), link(2), mknod(2), pipe(2), read(2), time(2), 
unlink(2), utime(2), write(2), fs(4). 
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NAME 

stime — set time 

SYNOPSIS 

int stime (tp) 
long *tp; 

DESCRIPTION 

stime sets the system's idea of the time and date. Tp points to the value of time 
as measured in seconds from 00:00:00 GMT January 1, 1970. 

[EPERM] stime will fail if the effective user ID of the calling process is not 

super-user. 

SEE ALSO 

time(2). 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 
is returned and errno is set to indicate the error. 
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NAME 

sync — update super block 

SYNOPSIS 

void sync ( ) 

DESCRIPTION 

sync causes all information in memory that should be on disk to be written out. 
This includes modified super blocks, modified i-nodes, and delayed block I/O. 

It should be used by programs which examine a file system, for example fsck, df, 
etc. It is mandatory before a re-boot. 

The writing, although scheduled, is not necessarily complete upon return from 
sync. 
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NAME 

sys3b — machine specific functions 
SYNOPSIS 

#include <sys/sys3b.h> 

int sys3b (cmd, argl, arg2, arg3) 
int cmd, argl, arg2, arg3; 

DESCRIPTION 

sys3b implements machine specific functions. The cmd argument determines the 
function performed. The number of arguments expected is dependent on the 
function. 

Command GRNFLASH 

When cmd is GRNFLASH, no arguments are expected. This function starts the 
green LED flashing. Note that this command is only available to the super-user. 

Command GRNON 

When cmd is GRNON, no arguments are expected. This function turns the 
greed LED to a solid on state. Note that this command is only available to the 
super-user. 

Command RNVR 

When cmd is RNVR, an argument of type struct nvparams * is expected. 

struct nvparams { 
char *addr; 
char Mata; 
unsigned short cnt; 



This function reads cnt bytes at address addr in NVRAM into address data. Note 
that this command is only available to the super-user. 

Command RTODC 

When cmd is RTODC, an argument of type struct tvdc * is expected. 

struct tvdc { 

short htenths; short hsecs; short hmins; 
short hhours; short hdays; short hweekday; 
short hmonth; short hyear 



This function reads the hardware time of day clock and returns the data in the 
structure referred to by the argument. Note that this command is only available 
to the super-user. 

Command S3BSYM 

When cmd is S3BSYM, the symbol table created during a self-config boot process 
may be accessed. The symbols available via this command are defined in one of 
two places: the driver routines loaded or the variable specifications in the files in 
the /etc/master directory. Two arguments are expected; the first must be a 
pointer to a buffer into which the symbol table is copied, and the second must 
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be an integer containing the total size of the buffer. The format of the symbol 
table is: 



int size; /* symbol size in bytes * / 

int count; /* total number of symbols * / 



char name[]; 



long value; 



/* for each symbol ... */ 

/* name of symbol, padded with * / 
/* '\0' to next sizeof(long) * / 

/* boundary */ 

/* value of symbol * / 



Typically, the symbol table would be retrieved with two calls to sys3b. First, the 
size of the symbol table is obtained by calling sys3b with a buffer of one integer. 
This integer is then used to obtain a buffer large enough to contain the entire 
symbol table. The second invocation of sys3b with this newly obtained buffer 
retrieves the entire symbol table. 

#include <sys/sy s3b.lt > 



int size; /* size of buffer needed * / 

struct s3bsym ^buffer; /* buffer pointer * / 



sys3b( S3BSYM, (struct s3bsym *) &size, sizeof(size) ); 
buffer = (struct s3bsym *) malloc( size ); 
sys3b( S3BSYM, buffer, size ); 

Command S3BCONF 

When and is S3BCONF, the configuration table created during a self-config boot 
process may be accessed. This table contains the names and locations of the 
devices supported by the currently running UNIX system, the names of all 
software modules included in the system, and the names of all devices in the 
EDT that were ignored. Two arguments are expected; the first must be a pointer 
to a buffer into which the configuration table is copied, and the second must be 



an integer 


containing the 


total size of the buffer. The format of the 


configuration table is: 




int 


ndev; 


/* total number of entries */ 






/* for each entry ... */ 


long 


timestamp; 


/* f timdat from file header */ 


char 


name[14]; 


/* name of device/module */ 


char 


flag; 


/* configuration information */ 

/* 0x80: device ignored */ 

/* 0x40: name[] is a driver */ 

/* 0x20: namejj is a software module */ 


char 


board; 


/* local bus address of device */ 
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Typically, the configuration table would be retrieved with two calls to sys3b . 
First, the number of entries is obtained by calling sys3b with a buffer of one 
integer. This integer is then used to calculate and obtain a buffer large enough 
to contain the entire configuration table. The second invocation of sys3b with 
this newly obtained buffer retrieves the configuration table. 

#include <sys/sys3b.h> 



int count; /* total number of devices */ 

int size; /* size of buffer needed */ 

struct s3bconf *buffer; /* buffer pointer */ 



x sys3b( S3BCONF, (struct s3bconf *) &count, sizeof(count) ); 

size = sizeof(int); 

size += count * sizeof(struct s3bc); 
buffer — (struct s3bconf *) malloc( size ); 
sys3b( S3BCONF, buffer, size ); 

Command S3BBOOT 

When cmd is S3BBOOT, the timestamp and boot program path name used for a 
self-config boot process may be accessed. The path name of the a. out format file 
which was booted, and the timestamp from the file header [see a.out( 4)] are 
saved. One argument is expected; a pointer to a buffer into which the informa- 
tion is copied. The format of this information is: 

long timestamp; /* f timdat from file header */ 
char path[100]; /* path name */ 

This information would be retrieved with a single call to sys3b. 

#include <sys/sys3b.h> 

struct s3bboot buffer; /* buffer */ 

sys3b( S3BBOOT, &buffer ); 

Command S3BAUTO 

When cmd is S3BAUTO, no arguments are expected. This function returns a 
boolean value in answer to the question, "Was the last boot an auto-config boot, 
or was a fully configured file booted?" The value returned is zero if a fully 
configured file (such as /unix) was booted. The integer value 1 is returned if 
the preceeding boot was an auto-config boot. The value is undefined if the 
system was booted in "magic mode." Note that this command is available only 
to the super-user. 

Command S3BFPHW 

When cmd is S3BFPHW, an indication of whether or not a MAU is present is 
returned. (See the Introduction to this manual for a description of the MAU.) 
One argument, the address of an int, is expected. On return from the system 
call, this int will contain a 1 if a MAU is present or a 0 if a MAU is not present. 
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If the address of the int is not valid (i.e. not word aligned, nor user accessible, 
etc.) EFAULT will be returned. 

To determine whether a MAU is present, the following should be done: 

#include <sys/sys3b.h> 

int maujpresent; 
sys3b(S3BFPHW, &mau_present); 

If this command succeeds, it returns 0 to the calling process. This call will fail, 
returning -1, if one or more of the following is true: 

[EFAULT] mau_present is not an integer, 

[EFAULT] &mau_present is an invalid address. 

Command S3BSWPI 

Note: This cmd is available only with System V Releases 2.1 and 3.0 software. 

When cmd is S3BSWPI, individual swapping areas may be added, deleted or the 
current areas determined. The address of an appropriately primed swap buffer is 
passed as the only argument. (Refer to sys/swap.h header file for details of 
loading the buffer.) 

The format of the swap buffer is: 
struct swapint { 



char 


sicmd; 


/♦command: list, add, delete*/ 


char 


*si_buf; 


/♦swap file path pointer*/ 


int 


siswplo; 


/♦start block*/ 


int 


sinblks; 


/♦swap size*/ 



Note that the add and delete options of the command may only be exercised by 
the super-user. 

Typically, a swap area is added by a single call to sys3b. First, the swap buffer 
is primed with appropriate entries for the structure members. Then sys3b is 
invoked. 

#include <sys/sys3b.h> 

#inclttde < sys/swap.h > 

struct swapint swapbuf; /*swap into buffer ptr*/ 

sys3b(S3BSWPI, &swapbuf); 

If this command succeeds, it returns 0 to the calling process. This command 
fails, returning -1, if one or more of the following is true: 

[EFAULT] Swapbuf points to an invalid address 

[EFAULT] Swapbuf. sijbuf points to an invalid address 
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[ENOTBLK] Swap area specified is not a block special device 

[EEXIST] Swap area specified has already been added 

[ENOSPC] Too many swap areas in use (if adding) 

[ENOMEM] Tried to delete last remaining swap area 

[EINVAL] Bad arguments 

[ENOMEM] No place to put swapped pages when deleting a swap area 

Command STIME 

When cmd is STIME, an argument of type long is expected. This function sets 
the system time and date. The argument contains the time as measured in 
seconds from 00:00:00 GMT January 1, 1970. Note that this command is only 
available to the super-user. 

Command WNVR 

When cmd is WNVR, an argument of type struct nvparams * is expected (see 
command RNVR). This function writes cnt bytes into address addr in NVRAM 
from address data. Note that this command is only available to the super-user. 

SEE ALSO 

sync(2), a.out(4). 

swap(lM) in the System Administrator's Reference Manual. 

DIAGNOSTICS 

Upon successful completion, the value returned depends on cmd as follows: 

S3BSYM A value of zero. 

S3BCONF A value of zero. 

S3BBOOT A value of zero. 

S3BAUTO A value of zero if a fully-configured file (such as 

/unix) was booted. A value of one if an auto-config 
boot was performed. 

Otherwise, a value of —1 is returned and errno is set to indicate the error. When 
cmd is invalid, errno is set to EINVAL on return. 
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NAME 

sysfs — get file system type information 
SYNOPSIS 

#include <sys/fstyp.h> 

#include <sys/fsid.h> 

int sysfs (opcode, fsname) 
int opcode; 
char *fsname; 

int sysfs (opcode, fsindex, buf) 
int opcode; 
int fs index; 
char *buf; 

int sysfs (opcode) 
int opcode; 

DESCRIPTION 

sysfs returns information about the file system types configured in the system. 
The number of arguments accepted by sysfs varies and depends on the opcode. 
The currently recognized opcodes and their functions are described below: 

GETFSIND translates fsname, a null-terminated file-system 

identifier, into a file-system type index. 

GETFSTYP translates fsjndex, a file-system type index, into a 

null-terminated file-system identifier and writes it into 
the buffer pointed to by buf ; this buffer must be at 
least of size FSTYPSZ as defined in <sys/fstyp.h > . 

GETNFSTYP returns the total number of file system types 

configured in the system. 

sysfs will fail if one or more of the following are true: 

[EINVAL] Fsname points to an invalid file-system identifier; 

fsjndex is zero, or invalid; opcode is invalid. 

[EFAULT] Buf or fsname point to an invalid user address. 

DIAGNOSTICS 

Upon successful completion, sysfs returns the file-system type index if the opcode 
is GETFSIND, a value of 0 if the opcode is GETFSTYP, or the number of file 
system types configured if the opcode is GETNFSTYP. Otherwise, a value of -1 
is returned and errno is set to indicate the error. 
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NAME 

time — get time 
SYNOPSIS 

#include <sys/types.h> 

time t time (tloc) 
long *tloc; 

DESCRIPTION 

time returns the value of time in seconds since 00:00:00 GMT, January 1, 1970. 

If tloc is non-zero, the return value is also stored in the location to which tloc 
points. 

SEE ALSO 

stime(2). 

WARNING 

time fails and its actions are undefined if tloc points to an illegal address. 
DIAGNOSTICS 

Upon successful completion, time returns the value of time. Otherwise, a value 
of —1 is returned and errno is set to indicate the error. 
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NAME 

times — get process and child process times 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/times.h> 

long times (buffer) 
struct tms *buffer; 

DESCRIPTION 

times fills the structure pointed to by buffer with time-accounting information. 
The following are the contents of this structure: 

struct tms { 

timet tmsutime; 
time_t tms_stime; 
time_t tms_cutime; 
time t tms cstime; 

}; 

This information comes from the calling process and each of its terminated child 
processes for which it has executed a wait. All times are reported in clock ticks 
per second. Clock ticks are a system-dependent parameter. The specific value 
for an implementation is defined by the variable HZ, found in the include file 
param.h. 

Tms_utime is the CPU time used while executing instructions in the user space of 
the calling process. 

Tms_stime is the CPU time used by the system on behalf of the calling process. 
Tms_cutime is the sum of the tmsjitimes and tms_cutime s of the child processes. 
Tms_cstime is the sum of the tms_stime s and tms_cstime s of the child processes. 
[EFAULT] times will fail if buffer points to an illegal address. 

SEE ALSO 

exec(2), fork(2), time(2), wait(2). 

DIAGNOSTICS 

Upon successful completion, times returns the elapsed real time, in clock ticks 
per second, from an arbitrary point in the past (e.g., system start-up time). This 
point does not change from one invocation of times to another. If times fails, a 
—1 is returned and errno is set to indicate the error. On a 3B2 Computer clock 
ticks occur 100 times per second. 
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NAME 

uadmin — administrative control 
SYNOPSIS 

#include <sys/uadmin.h> 

int uadmin (cmd, fen, mdep) 
int cmd, fen, mdep; 

DESCRIPTION 

uadmin provides control for basic administrative functions. This system call is 
tightly coupled to the system administrative procedures and is not intended for 
general use. The argument mdep is provided for machine-dependent use and is 
not defined here. 

As specified by cmd, the following commands are available: 

A SHUTDOWN The system is shutdown. All user processes are killed, the 
buffer cache is flushed, and the root file system is unmounted. 
The action to be taken after the system has been shut down is 
specified by fen. The functions are generic; the hardware capa- 
bilities vary on specific machines. 

AD HALT Halt the processor and turn off the power. 

AD BOOT Reboot the system, using /unix. 

AD IBOOT Interactive reboot; user is prompted for system 
name. 

AREBOOT The system stops immediately without any further processing. 
The action to be taken next is specified by fen as above. 

A REMOUNT The root file system is mounted again after having been fixed. 
This should be used only during the startup process. 

uadmin fails if any of the following are true: 

[EPERM] The effective user ID is not super-user. 

DIAGNOSTICS 

Upon successful completion, the value returned depends on cmd as follows: 

AJSHUTDOWN Never returns. 

A REBOOT Never returns. 

AREMOUNT 0 

Otherwise, a value of -1 is returned and errno is set to indicate the error. 
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NAME 

ulimit — get and set user limits 

SYNOPSIS 

long ulimit (cmd, newlimit) 

int cmd; 

long newlimit; 

DESCRIPTION 

This function provides for control over process limits. The cmd values available 
are: 

1 Get the regular file size limit of the process. The limit is in units of 512- 
byte blocks and is inherited by child processes. Files of any size can be 
read. 

2 Set the regular file size limit of the process to the value of newlimit. Any 
process may decrease this limit, but only a process with an effective user ID 
of super-user may increase the limit, ulimit fails and the limit is 
unchanged if a process with an effective user ID other than super-user 
attempts to increase its regular file size limit. [EPERM] 

3 Get the maximum possible break value [see brk( 2)]. 

SEE ALSO 

brk(2), write(2). 

WARNING 

ulimit is effective in limiting the growth of regular files. Pipes are currently lim- 
ited to 5,120 bytes. 

DIAGNOSTICS 

Upon successful completion, a non-negative value is returned. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 
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NAME 

umask — set and get file creation mask 

SYNOPSIS 

int umask (cmask) 
int cmask; 

DESCRIPTION 

umask sets the process's file mode creation mask to cmask and returns the pre- 
vious value of the mask. Only the low-order 9 bits of cmask and the file mode 
creation mask are used. 

SEE ALSO 

chmod(2), creat(2), mknod(2), open(2). 
mkdir(l), sh(l) in the User's Reference Manual. 

DIAGNOSTICS 

The previous value of the file mode creation mask is returned. 
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NAME 

umount — unmount a file system 

SYNOPSIS 

int umount (file) 
char *file; 



DESCRIPTION 

umount requests that a previously mounted file system contained on the block 
special device or directory identified by file be unmounted. File is a pointer to a 
path name. After unmounting the file system, the directory upon which the file 
system was mounted reverts to its ordinary interpretation. 

umount may be invoked only by the super-user. 
umount will fail if one or more of the following are true: 



[EPERM] 

[EINVAL] 

[ENOTBLK] 

[EINVAL] 

[EBUSY] 

[EFAULT] 

[EREMOTE] 

[ENOLINK] 

[EMULTIHOP] 



The process's effective user ID is not super-user. 

File does not exist. 

File is not a block special device. 

File is not mounted. 

A file on file is busy. 

File points to an illegal address. 

File is remote. 

File is on a remote machine, and the link to that machine is no 
longer active. 

Components of the path pointed to by file require hopping to 
multiple remote machines. 



SEE ALSO 

mount(2). 



DIAGNOSTICS 

Upon successful completion a value of 0 is returned. Otherwise, a value of — 1 
is returned and errno is set to indicate the error. 
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NAME 

uname — get name of current UNIX system 
SYNOPSIS 

#include <sys/utsname.h> 

int uname (name) 
struct utsname *name; 

DESCRIPTION 

uname stores information identifying the current UNIX system in the structure 
pointed to by name. 

uname uses the structure defined in <sys/utsname.h> whose members are: 

char sysname[9]; 
char nodename[9]; 
char release[9]; 
char version[9]; 
char machine[9]; 

uname returns a null-terminated character string naming the current UNIX system 
in the character array sysname. Similarly, nodename contains the name that the 
system is known by on a communications network. Release and version further 
identify the operating system. Machine contains a standard name that identifies 
the hardware that the UNIX system is running on. 

[EFAULT] uname will fail if name points to an invalid address. 

SEE ALSO 

uname(l) in the User's Reference Manual. 

DIAGNOSTICS 

Upon successful completion, a non-negative value is returned. Otherwise, a 
value of —1 is returned and errno is set to indicate the error. 
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NAME 

unlink — remove directory entry 



SYNOPSIS 

int unlink (path) 
char *path; 



DESCRIPTION 

unlink removes the directory entry named by the path name pointed to by path. 
The named file is unlinked unless one or more of the following are true: 
[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied for a component of the path prefix. 

[EACCES] Write permission is denied on the directory containing the link 

to be removed. 



[EPERM] 

[EBUSY] 

[ETXTBSY] 

[EROFS] 

[EFAULT] 

[EINTR] 

[ENOLINK] 

[EMULTIHOP] 



The named file is a directory and the effective user ID of the 
process is not super-user. 

The entry to be unlinked is the mount point for a mounted file 
system. 

The entry to be unlinked is the last link to a pure procedure 
(shared text) file that is being executed. 

The directory entry to be unlinked is part of a read-only file 
system. 

Path points outside the process's allocated address space. 

A signal was caught during the unlink system call. 

Path points to a remote machine and the link to that machine is 
no longer active. 

Components of path require hopping to multiple remote 
machines. 



When all links to a file have been removed and no process has the file open, the 
space occupied by the file is freed and the file ceases to exist. If one or more 
processes have the file open when the last link is removed, the removal is post- 
poned until all references to the file have been closed. 

SEE ALSO 

close(2), link(2), open(2). 

rm(l) in the User's Reference Manual. 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 
is returned and errno is set to indicate the error. 
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NAME 

ustat — get file system statistics 
SYNOPSIS 

#include <sys/types.h> 
#include <ustat.h> 



int ustat (dev, buf) 
dev t dev; 
struct ustat *buf; 



DESCRIPTION 

ustat returns information about a mounted file system. Dev is a device number 
identifying a device containing a mounted file system. Buf is a pointer to a ustat 
structure that includes the following elements: 



daddr t ftfree; 
ino_t ftinode; 
char f_fname[6]; 

char f_fpack[6]; 



/* Total free blocks */ 

/* Number of free inodes */ 
/* Filsys name */ 

/* Filsys pack name */ 



ustat will fail if one or more of the following are true: 



[EINVAL] 

[EFAULT] 

[EINTR] 

[ENOLINK] 

[ECOMM] 

SEE ALSO 

stat(2), fs(4). 



Dev is not the device number of a device containing a mounted 
file system. 

Buf points outside the process's allocated address space. 

A signal was caught during a ustat system call. 

Dev is on a remote machine and the link to that machine is no 
longer active. 

Dev is on a remote machine and the link to that machine is no 
longer active. 



DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of — 1 
is returned and errno is set to indicate the error. 
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NAME 

utime — set file access and modification times 
SYNOPSIS 

#include <sys/types.h> 
int utime (path, times) 
char *path; 

struct utimbuf *times; 

DESCRIPTION 

Path points to a path name naming a file, utime sets the access and modification 
times of the named file. 

If times is NULL, the access and modification times of the file are set to the 
current time. A process must be the owner of the file or have write permission 
to use utime in this manner. 

If times is not NULL, times is interpreted as a pointer to a utimbuf structure and 
the access and modification times are set to the values contained in the desig- 
nated structure. Only the owner of the file or the super-user may use utime this 
way. 

The times in the following structure are measured in seconds since 00:00:00 
GMT, Jan. 1, 1970. 

struct utimbuf { 

time_t actime; /* access time */ 
time_t modtime; /* modification time */ 



utime will fail if one or more of the following are true: 

[ENOENT] The named file does not exist. 

[ENOTDIR] A component of the path prefix is not a directory. 

[EACCES] Search permission is denied by a component of the path prefix. 

[EPERM] The effective user ID is not super-user and not the owner of the 

file and times is not NULL. 

[EACCES] The effective user ID is not super-user and not the owner of the 

file and times is NULL and write access is denied. 

[EROFS] The file system containing the file is mounted read-only. 

[EFAULT] Times is not NULL and points outside the process's allocated 

address space. 

[EFAULT] Path points outside the process's allocated address space. 

[EINTR] A signal was caught during the utime system call. 

[ENOLINK] Path points to a remote machine and the link to that machine is 
no longer active. 

[EMULTIHOP] Components of path require hopping to multiple remote 
machines. 



SEE ALSO 

stat(2). 
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DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of — 1 
is returned and errno is set to indicate the error. 
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NAME 

wait — wait for child process to stop or terminate 

SYNOPSIS 

int wait (stat loc) 
int *stat_loc; 

DESCRIPTION 

wait suspends the calling process until until one of the immediate children ter- 
minates or until a child that is being traced stops, because it has hit a break 
point. The wait system call will return prematurely if a signal is received and if 
a child process stopped or terminated prior to the call on wait , return is 
immediate. 

If stat Joe is non-zero, 16 bits of information called status are stored in the low 
order 16 bits of the location pointed to by stat Joe. Status can be used to 
differentiate between stopped and terminated child processes and if the child 
process terminated, status identifies the cause of termination and passes useful 
information to the parent. This is accomplished in the following manner: 

If the child process stopped, the high order 8 bits of status will contain 
the number of the signal that caused the process to stop and the low 
order 8 bits will be set equal to 0177. 

If the child process terminated due to an exit call, the low order 8 bits of 
status will be zero and the high order 8 bits will contain the low order 8 
bits of the argument that the child process passed to exit [see exit (2)]. 

If the child process terminated due to a signal, the high order 8 bits of 
status will be zero and the low order 8 bits will contain the number of 
the signal that caused the termination. In addition, if the low order 
seventh bit (i.e., bit 200) is set, a "core image" will have been produced 
[see signal (2)]. 

If a parent process terminates without waiting for its child processes to ter- 
minate, the parent process ID of each child process is set to 1. This means the 
initialization process inherits the child processes [see intro ( 2)]. 

wait will fail and return immediately if one or more of the following are true: 
[ECHILD] The calling process has no existing unwaited-for child processes. 

SEE ALSO 

exec(2), exit(2), fork(2), intro(2), pause(2), ptrace(2), signal(2). 

WARNING 

wait fails and its actions are undefined if stat Joe points to an invalid address. 

See WARNING in signal (2). 
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DIAGNOSTICS 

If wait returns due to the receipt of a signal, a value of —1 is returned to the cal- 
ling process and errno is set to EINTR. If wait returns due to a stopped or ter- 
minated child process, the process ID of the child is returned to the calling pro- 
cess. Otherwise, a value of —1 is returned and errno is set to indicate the error. 
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NAME 

write — write on a file 
SYNOPSIS 

int write (fildes, buf, nbyte) 
int fildes; 
char *buf; 
unsigned nbyte; 

DESCRIPTION 

fildes is a file descriptor obtained from a creat( 2), open( 2), dup( 2), fcntl( 2), or 
pipe (2) system call. 

write attempts to write nbyte bytes from the buffer pointed to by buf to the file 
associated with the fildes. 

On devices capable of seeking, the actual writing of data proceeds from the posi- 
tion in the file indicated by the file pointer. Upon return from write, the file 
pointer is incremented by the number of bytes actually written. 

On devices incapable of seeking, writing always takes place starting at the 
current position. The value of a file pointer associated with such a device is 
undefined. 

If the OAPPEND flag of the file status flags is set, the file pointer will be set to 
the end of the file prior to each write. 

For regular files, if the O SYNC flag of the file status flags is set, the write will 
not return until both the file data and file status have been physically updated. 
This function is for special applications that require extra reliability at the cost of 
performance. For block special files, if 0_SYNC is set, the write will not return 
until the data has been physically updated. 

A write to a regular file will be blocked if mandatory file/record locking is set 
[see chmod(2)\, and there is a record lock owned by another process on the seg- 
ment of the file to be written. If 0_NDELAY is not set, the write will sleep until 
the blocking record lock is removed. 

For STREAMS [see intro( 2)] files, the operation of write is determined by the 
values of the minimum and maximum nbyte range ("packet size") accepted by 
the stream. These values are contained in the topmost stream module. Unless 
the user pushes [see I PUSH in streamio(7)] the topmost module, these values can 
not be set or tested from user level. If nbyte falls within the packet size range, 
nbyte bytes will be written. If nbyte does not fall within the range and the 
minimum packet size value is zero, write will break the buffer into maximum 
packet size segments prior to sending the data downstream (the last segment 
may contain less than the maximum packet size). If nbyte does not fall within 
the range and the minimum value is non-zero, write will fail with errno set to 
ERANGE. Writing a zero-length buffer (nbyte is zero) sends zero bytes with zero 
returned. 

For STREAMS files, if ONDELAY is not set and the stream can not accept data 
(the stream write queue is full due to internal flow control conditions), write will 
block until data can be accepted. O NDELAY will prevent a process from 
blocking due to flow control conditions. If O NDELAY is set and the stream can 
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not accept data, write will fail. If ONDELAY is set and part of the buffer has 
been written when a condition in which the stream can not accept additional 
data occurs, write will terminate and return the number of bytes written. 



write will fail and the file pointer will remain unchanged if one or more of the 
following are true: 



[EAGAIN] 

[EAGAIN] 

[EAGAIN] 

[EBADF] 

[EDEADLK] 



Mandatory file/record locking was set, O NDELAY was set, and 
there was a blocking record lock. 

Total amount of system memory available when reading via 
raw IO is temporarily insufficient. 

Attempt to write to a stream that can not accept data with the 
O NDELAY flag set. 

fildes is not a valid file descriptor open for writing. 

The write was going to go to sleep and cause a deadlock situa- 
tion to occur. 



[EFAULT] 

[EFBIG] 

[EINTR] 

[EINVAL] 

[ENOLCK] 

[ENOLINK] 

[ENOSPC] 

[ENXIO] 



buf points outside the process's allocated address space. 

An attempt was made to write a file that exceeds the process's 
file size limit or the maximum file size [see ulimit( 2)]. 

A signal was caught during the write system call. 

Attempt to write to a stream linked below a multiplexor. 

The system record lock table was full, so the write could not go 
to sleep until the blocking record lock was removed. 

fildes is on a remote machine and the link to that machine is no 
longer active. 

During a write to an ordinary file, there is no free space left on 
the device. 

A hangup occurred on the stream being written to. 



[EPIPE and SIGPIPE signal] 

An attempt is made to write to a pipe that is not open for 
reading by any process. 

[ERANGE] Attempt to write to a stream with nbyte outside specified 

minimum and maximum write range, and the minimum value is 
non-zero. 



If a write requests that more bytes be written than there is room for (e.g., the 
ulimit [see ulimit( 2)] or the physical end of a medium), only as many bytes as 
there is room for will be written. For example, suppose there is space for 20 
bytes more in a file before reaching a limit. A write of 512-bytes will return 20. 
The next write of a non-zero number of bytes will give a failure return (except as 
noted below). 

If the file being written is a pipe (or FIFO) and the O NDELAY flag of the file flag 
word is set, then write to a full pipe (or FIFO) will return a count of 0. Other- 
wise (0_NDELAY clear), writes to a full pipe (or FIFO) will block until space 
becomes available. 
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A write to a STREAMS file can fail if an error message has been received at the 
stream head. In this case, errno is set to the value included in the error message. 

SEE ALSO 

creat(2), dup(2), fcntl(2), intro(2), lseek(2), open(2), pipe(2), ulimit(2). 
DIAGNOSTICS 

Upon successful completion the number of bytes actually written is returned. 
Otherwise, —1 is returned and errno is set to indicate the error. 
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NAME 

intro — introduction to functions and libraries 
DESCRIPTION 

This section describes functions found in various libraries, other than those func- 
tions that directly invoke UNIX system primitives, which are described in Sec- 
tion 2 of this volume. Certain major collections are identified by a letter after 
the section number: 

(3C) These functions, together with those of Section 2 and those marked (3S), 
constitute the Standard C Library libc, which is automatically loaded by 
the C compiler, cc( 1). (For this reason the (3C) and (3S) sections together 
comprise one section of this manual.) The link editor ld( 1) searches this 
library under the —lc option. A "shared library" version of libc can be 
searched using the — lc_s option, resulting in smaller a.outs. Declarations 
for some of these functions may be obtained from #include files indi- 
cated on the appropriate pages. 

(3S) These functions constitute the "standard I/O package" [see stdio( 3S)]. 
These functions are in the library libc, already mentioned. Declarations 
for these functions may be obtained from the #include file <stdio.h>. 
(3M) These functions constitute the Math Library, libm . They are automatically 
loaded as needed by the FORTRAN compiler /77( 1). They are not 
automatically loaded by the C compiler, cc(l); however, the link editor 
searches this library under the — lm option. Declarations for these func- 
tions may be obtained from the #include file <math.h>. Several gen- 
erally useful mathematical constants are also defined there [see math(5)\. 
(3N) This contains sets of functions constituting the Network Services library. 
These sets provide protocol independent interfaces to networking services 
based on the service definitions of the OSI (Open Systems Interconnec- 
tion) reference model. Application developers access the function sets 
that provide services at a particular level. 

The function sets contained in the library are: 

TRANSPORT INTERFACE (TI) - provide the services of the OSI Tran- 
sport Layer. These services provide reliable end-to-end data 
transmission using the services of an underlying network. Applica- 
tions written using the TI functions are independent of the under- 
lying protocols. Declarations for these functions may be obtained 
from the #include file <tiuser.h>. The link editor ld( 1) searches 
this library under the — lnsls option. 

(3X) Various specialized libraries. The files in which these libraries are found 
are given on the appropriate pages. 

(3F) These functions constitute the FORTRAN intrinsic function library, libF77. 
These functions are automatically available to the FORTRAN programmer 
and require no special invocation of the compiler. 

DEFINITIONS 

A character is any bit pattern able to fit into a byte on the machine. The null 
character is a character with value 0, represented in the C language as '\0'. A 
character array is a sequence of characters. A null-terminated character array is a 
sequence of characters, the last of which is the null character. A string is a 
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designation for a null-terminated character array . The null string is a character 
array containing only the null character. A NULL pointer is the value that is 
obtained by casting 0 into a pointer. The C language guarantees that this value 
will not match that of any legitimate pointer, so many functions that return 
pointers return it to indicate an error. NULL is defined as 0 in <stdio.h>; the 
user can include an appropriate definition if not using <stdio.h>. 

Many groups of FORTRAN intrinsic functions have generic function names that 
do not require explicit or implicit type declaration. The type of the function will 
be determined by the type of its argument(s). For example, the generic function 
max will return an integer value if given integer arguments (maxO), a real value if 
given real arguments ( amaxl ), or a double-precision value if given double- 
precision arguments (dmaxl). 

Netbuf In the Network Services library, netbuf is a structure used in various 
Transport Interface (TI) functions to send and receive data and information. It 
contains the following members: 

unsigned int maxlen; 
unsigned int len; 
char *buf; 

Buf points to a user input and/or output buffer. Len generally specifies the 
number of bytes contained in the buffer. If the structure is used for both input 
and output, the function will replace the user value of len on return. 

Maxlen generally has significance only when buf is used to receive output from 
the TI function. In this case, it specifies the physical size of the buffer, the max- 
imum value of len that can be set by the function. If maxlen is not large enough 
to hold the returned information, an TBUFOVFLW error will generally result. 
However, certain functions may return part of the data and not generate an 
error. 

FILES 

LIBDIR usually /lib 

LIBDIR/libc.a 

LIBDIR/libcs.a 

LIBDIR/libm.a 

LIBDIR/lib77.a 

/shlib/libc_s 

/shlib/libnsls (3N) 

/usr/lib/libnsl_s.a (3N) 

SEE ALSO 

ar(l), cc(l), ld(l), lint(l), nm(l), intro(2), stdio(3S), math(5). 
f77(l) in the FORTRAN Programming Language Manual. 

DIAGNOSTICS 

Functions in the C and Math Libraries (3C and 3M) may return the conventional 
values 0 or ±HUGE (the largest-magnitude single-precision floating-point 
numbers; HUGE is defined in the <math.h> header file) when the function is 
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undefined for the given arguments or when the value is not representable. In 
these cases, the external variable errno [see intro ( 2)] is set to the value EDOM or 
ERANGE. 

WARNING 

Many of the functions in the libraries call and/or refer to other functions and 
external variables described in this section and in Section 2 (System Calls). If a 
program inadvertently defines a function or external variable with the same 
name, the presumed library version of the function or external variable may not 
be loaded. The lint( 1) program checker reports name conflicts of this kind as 
"multiple declarations" of the names in question. Definitions for Sections 2, 3C, 
and 3S are checked automatically. Other definitions can be included by using 
the —1 option. (For example, — 1 m includes definitions for Section 3M, the Math 
Library.) Use of lint is highly recommended. 
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NAME 

a641, 164a — convert between long integer and base-64 ASCII string 

SYNOPSIS 

long a641 (s) 
char *s; 

char *164a (1) 
long 1; 

DESCRIPTION 

These functions are used to maintain numbers stored in base-64 ASCII characters. 
This is a notation by which long integers can be represented by up to six charac- 
ters; each character represents a "digit" in a radix-64 notation. 

The characters used to represent "digits" are . for 0, / for 1, 0 through 9 for 
2—11, A through Z for 12—37, and a through z for 38—63. 

a64l takes a pointer to a null-terminated base-64 representation and returns a 
corresponding long value. If the string pointed to by s contains more than six 
characters, a64l will use the first six. 

a64l scans the character string from left to right, decoding each character as a 6 
bit Radix 64 number. 

164a takes a long argument and returns a pointer to the corresponding base-64 
representation. If the argument is 0, 164a returns a pointer to a null string. 

CAVEAT 

The value returned by 1 64a is a pointer into a static buffer, the contents of which 
are overwritten by each call. 
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NAME 

abort — generate an IOT fault 

SYNOPSIS 

int abort ( ) 

DESCRIPTION 

abort does the work of exit( 2), but instead of just exiting, abort causes SIGABRT 
to be sent to the calling process. If SIGABRT is neither caught nor ignored, all 
stdio( 3S) streams are flushed prior to the signal being sent, and a core dump 
results. 

abort returns the value of the kill(2) system call. 

SEE ALSO 

sdb(l), exit(2), kill(2), signal(2). 

DIAGNOSTICS 

If SIGABRT is neither caught nor ignored, and the current directory is writable, a 
core dump is produced and the message "abort — core dumped" is written by 
the shell. 
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NAME 

abs — return integer absolute value 

SYNOPSIS 

int abs (i) 
int i; 

DESCRIPTION 

abs returns the absolute value of its integer operand. 

SEE ALSO 

floor(3M). 

CAVEAT 

In two's-complement representation, the absolute value of the negative integer 
with largest magnitude is undefined. Some implementations trap this error, but 
others simply ignore it. 
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NAME 

bsearch — binary search a sorted table 
SYNOPSIS 

#include <search.h> 

char *bsearch ((char *) key, (char *) base, nel, sizeof (*key), compar) 
unsigned nel; 
int (*compar)( ); 

DESCRIPTION 

bsearch is a binary search routine generalized from Knuth (6.2.1) Algorithm B. It 
returns a pointer into a table indicating where a datum may be found. The table 
must be previously sorted in increasing order according to a provided com- 
parison function. Key points to a datum instance to be sought in the table. Base 
points to the element at the base of the table. Nel is the number of elements in 
the table. Compar is the name of the comparison function, which is called with 
two arguments that point to the elements being compared. The function must 
return an integer less than, equal to, or greater than zero as accordingly the first 
argument is to be considered less than, equal to, or greater than the second. 

EXAMPLE 

The example below searches a table containing pointers to nodes consisting of a 
string and its length. The table is ordered alphabetically on the string in the 
node pointed to by each entry. 

This code fragment reads in strings and either finds the corresponding node and 
prints out the string and its length, or prints an error message. 

#include <stdio.h> 

#include <search.h> 

#define TABSIZE 1000 

f ) 
struct node { /* these are stored in the table */ 

char * string; 
int length; 

}; 

struct node table[TABSIZE]; /* table to be searched */ 



struct node *node_ptr, node; 

int node_compare( ); /* routine to compare 2 nodes */ 

char str_space[20]; /* space to read string into */ 
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} 

/* 



*/ 
int 

node_compare(nodel, node2) 
char *nodel, *node2; 

{ 

return (strcmp( 

((struct node *)nodel)— > string, 

((struct node *)node2)—> string)); 

NOTES 

The pointers to the key and the element at the base of the table should be of 
type pointer-to-element, and cast to type pointer-to-character. 

The comparison function need not compare every byte, so arbitrary data may be 
contained in the elements in addition to the values being compared. 

Although bsearch is declared as type pointer-to-character, the value returned 
should be cast into type pointer-to-element. 

SEE ALSO 

hsearch(3C), lsearch(3C), qsort(3C), tsearch(3C). 

DIAGNOSTICS 

A NULL pointer is returned if the key cannot be found in the table. 



(C Programming Language Utilities) BSEARCH(3C) 

node, string = strspace; 

while (scanf("%s'', node.string) != EOF) { 

nodejDtr = (struct node *)bsearch((char *)(&node), 

(char *)table, TABSIZE, 
sizeof(struct node), node_compare); 
if (node_ptr != NULL) { 

(void)printf("string = %20s, length = %d\n", 
node_ptr— > string, node_ptr— > length); 

} else { 

(void)printf("not found: %s\n", node.string); 

} 



This routine compares two nodes based on an 
alphabetical ordering of the string field. 
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NAME 

clock — report CPU time used 

SYNOPSIS 

long clock ( ) 

DESCRIPTION 

clock returns the amount of CPU time (in microseconds) used since the first call 
to clock. The time reported is the sum of the user and system times of the cal- 
ling process and its terminated child processes for which it has executed wait(l) r 
pclose( 3S), or system( 3S). 

The resolution of the clock is 10 milliseconds on AT&T 3B computers. 

SEE ALSO 

times(2), wait(2), popen(3S), system(3S). 

BUGS 

The value returned by clock is defined in microseconds for compatibility with 
systems that have CPU clocks with much higher resolution. Because of this, the 
value returned will wrap around after accumulating only 2147 seconds of CPU 
time (about 36 minutes). 
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NAME 

conv: toupper, tolower, _toupper, _tolower, toascii — translate characters 
SYNOPSIS 

#include <ctype.h> 

int toupper (c) 
int c; 

int tolower (c) 
int c; 

int toupper (c) 
int c; 

int tolower (c) 
int c; 

int toascii (c) 
int c; 

DESCRIPTION 

Toupper and tolower have as domain the range of getc( 3S): the integers from —1 
through 255. If the argument of toupper represents a lower-case letter, the result 
is the corresponding upper-case letter. If the argument of tolower represents an 
upper-case letter, the result is the corresponding lower-case letter. All other 
arguments in the domain are returned unchanged. 

The macros Joupper and Jolower, are macros that accomplish the same thing as 
toupper and tolower but have restricted domains and are faster. Joupper 
requires a lower-case letter as its argument; its result is the corresponding 
upper-case letter. The macro Jolower requires an upper-case letter as its argu- 
ment; its result is the corresponding lower-case letter. Arguments outside the 
domain cause undefined results. 

Toascii yields its argument with all bits turned off that are not part of a standard 
ASCII character; it is intended for compatibility with other systems. 

SEE ALSO 

ctype(3C), getc(3S). 
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NAME 

crypt, setkey, encrypt — generate hashing encryption 
SYNOPSIS 

char *crypt (key, salt) 
char *key, *salt; 

void setkey (key) 
char *key; 

void encrypt (block, ignored) 
char *block; 
int ignored; 

DESCRIPTION 

crypt is the password encryption function. It is based on a one way hashing 
encryption algorithm with variations intended (among other things) to frustrate 
use of hardware implementations of a key search. 

Key is a user's typed password. Salt is a two-character string chosen from the 
set [a-zA-ZO-9./]; this string is used to perturb the hashing algorithm in one of 
4096 different ways, after which the password is used as the key to encrypt 
repeatedly a constant string. The returned value points to the encrypted pass- 
word. The first two characters are the salt itself. 

The setkey and encrypt entries provide (rather primitive) access to the actual 
hashing algorithm. The argument of setkey is a character array of length 64 con- 
taining only the characters with numerical value 0 and 1. If this string is 
divided into groups of 8, the low-order bit in each group is ignored; this gives a 
56-bit key which is set into the machine. This is the key that will be used with 
the hashing algorithm to encrypt the string block with the function encrypt. 

The argument to the encrypt entry is a character array of length 64 containing 
only the characters with numerical value 0 and 1. The argument array is 
modified in place to a similar array representing the bits of the argument after 
having been subjected to the hashing algorithm using the key set by setkey. 
Ignored is unused by encrypt but it must be present. 

SEE ALSO 

getpass(3C), passwd(4). 

login(l), passwd(l) in the User's Reference Manual. 

CAVEAT 

The return value points to static data that are overwritten by each call. 
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NAME 

ctermid — generate file name for terminal 
SYNOPSIS 

#include <stdio.h> 
char *ctermid (s) 
char *s; 

DESCRIPTION 

ctermid generates the path name of the controlling terminal for the current pro- 
cess, and stores it in a string. 

If s is a NULL pointer, the string is stored in an internal static area, the contents 
of which are overwritten at the next call to ctermid, and the address of which is 
returned. Otherwise, s is assumed to point to a character array of at least 
L_ctermid elements; the path name is placed in this array and the value of s is 
returned. The constant L_ctermid is defined in the <stdio.h> header file. 

NOTES 

The difference between ctermid and ttyname (3C) is that ttyname must be handed 
a file descriptor and returns the actual name of the terminal associated with that 
file descriptor, while ctermid returns a string (/dev/tty) that will refer to the ter- 
minal if used as a file name. Thus ttyname is useful only if the process already 
has at least one file open to a terminal. 

SEE ALSO 

ttyname(3C). 
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NAME 

ctime, localtime, gmtime, asctime, tzset — convert date and time to string 
SYNOPSIS 

#include <sys/types.h> 

#include <time.h> 

char * ctime (clock) 
time t * clock; 

struct tm *localtime (clock) 
time t *clock; 

struct tm *gmtime (clock) 
time t *clock; 

char * asctime (tm) 
struct tm *tm; 

extern long timezone; 
extern int daylight; 
extern char *tzname[2]; 
void tzset ( ) 

DESCRIPTION 

ctime converts a long integer, pointed to by clock , representing the time in 
seconds since 00:00:00 GMT, January 1, 1970, and returns a pointer to a 26- 
Character string in the following form. All the fields have constant width. 

Sun Sep 16 01:03:52 1985\n\0 

Localtime and gmtime return pointers to "tm" structures, described below. Local- 
time corrects for the time zone and possible Daylight Savings Time; gmtime con- 
verts directly to Greenwich Mean Time (GMT), which is the time the UNIX 
system uses. 

Asctime converts a "tm" structure to a 26-character string, as shown in the 
above example, and returns a pointer to the string. 

Declarations of all the functions and externals, and the "tm" structure, are in the 
<time.h> header file. The structure declaration is: 

struct tm { 

int tm_sec; /* seconds (0 - 59) */ 

int tm min; /* minutes (0 - 59) */ 

int tm hour; /* hours (0 - 23) */ 

int tm mday; /* day of month (1 - 31) */ 

int tm mon; /* month of year (0 - 11) */ 

int tm_year; /* year — 1900 */ 

int tm_wday; /* day of week (Sunday — 0) */ 

int tm_yday; /* day of year (0 - 365) */ 

int tm isdst; 

}; 

Tmjsdst is non-zero if Daylight Savings Time is in effect. 
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The external long variable timezone contains the difference, in seconds, between 
GMT and local standard time (in EST, timezone is 5*60*60); the external variable 
daylight is non-zero if and only if the standard U.S.A. Daylight Savings Time 
conversion should be applied. The program knows about the peculiarities of 
this conversion in 1974 and 1975; if necessary, a table for these years can be 
extended. 

If an environment variable named TZ is present, asctime uses the contents of the 
variable to override the default time zone. The value of TZ must be a three- 
letter time zone name, followed by a number representing the difference 
between local time and Greenwich Mean Time in hours, followed by an optional 
three-letter name for a daylight time zone. For example, the setting for New 
Jersey would be EST5EDT. The effects of setting TZ are thus to change the 
values of the external variables timezone and daylight ; in addition, the time zone 
names contained in the external variable 

char *tzname[2] = { "EST", "EDT" }; 

are set from the environment variable TZ. The function tzset sets these external 
variables from TZ; tzset is called by asctime and may also be called explicitly by 
the user. 

Note that in most installations, TZ is set by default when the user logs on, to a 
value in the local /etc/profile file [see profile( 4)]. 

SEE ALSO 

time(2), getenv(3C), profile(4), environ(5). 

CAVEAT 

The return values point to static data whose content is overwritten by each call. 
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NAME 

ctype: isalpha, isupper, islower, isdigit, isxdigit, isalnum, isspace, ispunct, isprint, 
isgraph, iscntrl, isascii — classify characters 

SYNOPSIS 

#include <ctype.h> 

int isalpha (c) 
int c; 

DESCRIPTION 

These macros classify character-coded integer values by table lookup. Each is a 
predicate returning nonzero for true, zero for false. Isascii is defined on all 
integer values; the rest are defined only where isascii is true and on the single 
non-ASCII value EOF [— 1; see stdio( 3S)]. 

isalpha c is a letter. 

isupper c is an upper-case letter. 

islower c is a lower-case letter. 

isdigit c is a digit [0-9]. 

isxdigit c is a hexadecimal digit [0-9], [A-F] or [a-f]. 

isalnum c is an alphanumeric (letter or digit). 

isspace c is a space, tab, carriage return, newline, vertical tab, or form- 

feed. 

ispunct c is a punctuation character (neither control nor alphanumeric). 

isprint c is a printing character, code 040 (space) through 0176 (tilde). 

isgraph c is a printing character, like isprint except false for space. 

iscntrl c is a delete character (0177) or an ordinary control character 

(less than 040). 

isascii c is an ASCII character, code less than 0200. 

SEE ALSO 

stdio(3S), ascii(5). 

DIAGNOSTICS 

If the argument to any of these macros is not in the domain of the function, the 
result is undefined. 
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NAME 

cuserid — get character login name of the user 
SYNOPSIS 

#include <stdio.h> 

char *cuserid (s) 
char *s; 

DESCRIPTION 

cuserid generates a character-string representation of the login name that the 
owner of the current process is logged in under. If s is a NULL pointer, this 
representation is generated in an internal static area, the address of which is 
returned. Otherwise, s is assumed to point to an array of at least L_cuserid 
characters; the representation is left in this array. The constant L_cuserid is 
defined in the <stdio.h> header file. 

DIAGNOSTICS 

If the login name cannot be found, cuserid returns a NULL pointer; if s is not a 
NULL pointer, a null character (\0) will be placed at s[0 ] . 

SEE ALSO 

getlogin(3C), getpwent(3C). 
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NAME 

dial — establish an out-going terminal line connection 
SYNOPSIS 

#include <dial.h> 

int dial (call) 

CALL call; 

void undial (fd) 
int fd; 

DESCRIPTION 

dial returns a file-descriptor for a terminal line open for read/write. The argu- 
ment to dial is a CALL structure (defined in the <dial.h> header file). 

When finished with the terminal line, the calling program must invoke undial to 
release the semaphore that has been set during the allocation of the terminal 
device. 

The definition of CALL in the <dial.h> header file is: 
typedef struct { 



struct termio *attr; 


/♦ pointer to termio attribute struct */ 


int 


baud; 


/* transmission data rate */ 


int 


speed; 


/* 212A modem: low=300, high=1200 */ 


char 


♦line; 


/* device name for out-going line */ 


char 


♦telno; 


/* pointer to tel-no digits string */ 


int 


modem; 


/* specify modem control for direct lines */ 


char 


’‘‘device; 


/*Will hold the name of the device used 
to make a connection */ 


int 


devlen; 


/* The length of the device used to make 
connection */ 



} CALL; 

The CALL element speed is intended only for use with an outgoing dialed call, in 
which case its value should be either 300 or 1200 to identify the 113A modem, 
or the high- or low-speed setting on the 212A modem. Note that the 113A 
modem or the low-speed setting of the 21 2 A modem will transmit at any rate 
between 0 and 300 bits per second. However, the high-speed setting of the 
21 2 A modem transmits and receives at 1200 bits per secound only. The CALL 
element baud is for the desired transmission baud rate. For example, one might 
set baud to 110 and speed to 300 (or 1200). However, if speed set to 1200 baud 
must be set to high (1200). 

If the desired terminal line is a direct line, a string pointer to its device-name 
should be placed in the line element in the CALL structure. Legal values for 
such terminal device names are kept in the L-devices file. In this case, the value 
of the baud element need not be specified as it will be determined from the L- 
devices file. 
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The telno element is for a pointer to a character string representing the tele- 
phone number to be dialed. Such numbers may consist only of symbols 
described on the acu(7). The termination symbol will be supplied by the dial 
function, and should not be included in the telno string passed to dial in the 
CALL structure. 

The CALL element modem is used to specify modem control for direct lines. This 
element should be non-zero if modem control is required. The CALL element 
attr is a pointer to a termio structure, as defined in the termio.h header file. A 
NULL value for this pointer element may be passed to the dial function, but if 
such a structure is included, the elements specified in it will be set for the out- 
going terminal line before the connection is established. This is often important 
for certain attributes such as parity and baud-rate. 

The CALL element device is used to hold the device name (cul..) that establishes 
the connection. 

The CALL element dev Jen is the length of the device name that is copied into 
the array device. 

FILES 

/usr /lib / uucp /L-devices 
/usr /spool /uucp /LCK ..tty -device 

SEE ALSO 

alarm(2), read(2), write(2). 

acu(7), termio(7) in the System Administrator's Reference Manual. 
uucp(lC) in the User's Reference Manual. 

DIAGNOSTICS 

On failure, a negative value indicating the reason for the failure will be returned. 
Mnemonics for these negative indices as listed here are defined in the <dial.h> 
header file. 

INTRPT 
DHUNG 
NO_ANS 
ILLJBD 
APROB 
LPROB 
NOLdv 
DVNTA 
DV_NT_K 
NOBDA 
NOBDK 

WARNINGS 

The dial (3C) library function is not compatible with Basic Networking Utilities 
on UNIX System V Release 2.0. 

Including the <dial.h> header file automatically includes the < termio.h > 
header file. 

The above routine uses <stdio.h>, which causes it to increase the size of pro- 
grams, not otherwise using standard I/O, more than might be expected. 



— 1 /* interrupt occurred */ 

—2 /* dialer hung (no return from write) * / 

—3 /* no answer within 10 seconds */ 

—4 /* illegal baud-rate * / 

—5 /* acu problem (open() failure) * / 

—6 /* line problem (open() failure) */ 

—7 /* can't open LDEVS file */ 

—8 /* requested device not available */ 

—9 /* requested device not known */ 

—10 /* no device available at requested baud */ 

—11 /* no device known at requested baud */ 
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BUGS 

An alarm( 2) system call for 3600 seconds is made (and caught) within the dial 
module for the purpose of 7 "touching" the LCK.. file and constitutes the device 
allocation semaphore for the terminal device. Otherwise, uucp( 1C) may simply 
delete the LCK.. entry on its 90-minute clean-up rounds. The alarm may go off 
while the user program is in a read( 2) or write (2) system call, causing an 
apparent error return. If the user program expects to be around for an hour or 
more, error returns from reads should be checked for (errno==EINTR), and the 
read possibly reissued. 
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NAME 

drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48, seed48, 
lcong48 — generate uniformly distributed pseudo-random numbers 

SYNOPSIS 

double drand48 ( ) 

double erand48 (xsubi) 
unsigned short xsubi[3]; 

long lrand48 ( ) 

long nrand48 (xsubi) 
unsigned short xsubi[3]; 

long mrand48 ( ) 

long jrand48 (xsubi) 
unsigned short xsubi[3]; 

void srand48 (seedval) 
long seedval; 

unsigned short *seed48 (seedl6v) 
unsigned short seedl6v[3]; 

void lcong48 (param) 
unsigned short param[7]; 

DESCRIPTION 

This family of functions generates pseudo-random numbers using the well- 
known linear congruential algorithm and 4 8 -bit integer arithmetic. 

Functions drand48 and erand48 return non-negative double-precision floating- 
point values uniformly distributed over the interval [0.0, 1.0). 

Functions lrand48 and nrand48 return non-negative long integers uniformly dis- 
tributed over the interval [0, 2 31 ). 

Functions mrand48 and jrand48 return signed long integers uniformly distributed 
over the interval [— 2 31 , 2 31 ). 

Functions srand48, seed48 and lcong48 are initialization entry points, one of 
which should be invoked before either drand48, lrand48 or mrand48 is called. 
(Although it is not recommended practice, constant default initializer values will 
be supplied automatically if drand48, lrand48 or mrand48 is called without a prior 
call to an initialization entry point.) Functions erand48, nrand48 and jrand48 do 
not require an initialization entry point to be called first. 

All the routines work by generating a sequence of 48-bit integer values, X/, 
according to the linear congruential formula 

X n +l ~ (aX n d"C)mod m Tl^O. 

The parameter m — 2, hence 48-bit integer arithmetic is performed. Unless 
lcong48 has been invoked, the multiplier value a and the addend value C are 
given by 

a - 5DEECE66D 16 - 273673163155 8 
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c — B 16 - 13s- 

The value returned by any of the functions drand48, erand48, lrand48, nrand48, 
mrand48 or jrand48 is computed by first generating the next 48-bit X; in the 
sequence. Then the appropriate number of bits, according to the type of data 
item to be returned, are copied from the high-order (leftmost) bits of X* and 
transformed into the returned value. 

The functions drand48, lrand48 and mrand48 store the last 48-bit X/ generated in 
an internal buffer, and must be initialized prior to being invoked. The functions 
erand48, nrand48 and jrand48 require the calling program to provide storage for 
the successive X; values in the array specified as an argument when the func- 
tions are invoked. These routines do not have to be initialized; the calling pro- 
gram must place the desired initial value of X* into the array and pass it as an 
argument. By using different arguments, functions erand48, nrand48 and jrand48 
allow separate modules of a large program to generate several independent 
streams of pseudo-random numbers, i.e., the sequence of numbers in each 
stream will not depend upon how many times the routines have been called to 
generate numbers for the other streams. 

The initializer function srand48 sets the high-order 32 bits of X; to the 32 bits 
contained in its argument. The low-order 16 bits of X/ are set to the arbitrary 
value 330E26. 

The initializer function seed48 sets the value of X/ to the 48-bit value specified 
in the argument array. In addition, the previous value of X; is copied into a 
4 8 -bit internal buffer, used only by seed48, and a pointer to this buffer is the 
value returned by seed48. This returned pointer, which can just be ignored if not 
needed, is useful if a program is to be restarted from a given point at some 
future time — use the pointer to get at and store the last X; value, and then use 
this value to reinitialize via seed48 when the program is restarted. 

The initialization function lcong48 allows the user to specify the initial X,-, the 
multiplier value a, and the addend value C. Argument array elements param[0- 
2] specify X/, param[3-5] specify the multiplier a, and param[6] specifies the 16- 
bit addend C. After lcong48 has been called, a subsequent call to either srand48 
or seed48 will restore the "standard" multiplier and addend values, a and C, 
specified on the previous page. 

NOTES 

The source code for the portable version can be used on computers which do 
not have floating-point arithmetic. In such a situation, functions drand48 and 
erand48 are replaced by the two new functions below. 

long irand48 (m) 
unsigned short m; 

long krand48 (xsubi, m) 
unsigned short xsubi[3], m; 

Functions irand48 and krand48 return non-negative long integers uniformly dis- 
tributed over the interval [0, m— 1]. 

SEE ALSO 

rand(3C). 
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NAME 

dup2 — duplicate an open file descriptor 
SYNOPSIS 

int dup2 (fildes, fildes2) 
int fildes, fildes2; 

DESCRIPTION 

Fildes is a file descriptor referring to an open file, and fildes! is a non-negative 
integer less than NOFILES. dup2 causes fildes2 to refer to the same file as fildes. 
If fildes2 already referred to an open file, it is closed first. 

dup2 will fail if one or more of the following are true: 

[EBADF] Fildes is not a valid open file descriptor. 

[EMFILE] NOFILES file descriptors are currently open. 

SEE ALSO 

creat(2), close(2), exec(2), fcntl(2), open(2), pipe(2), lockf(3C). 

DIAGNOSTICS 

Upon successful completion a non-negative integer, namely the file descriptor, is 
returned. Otherwise, a value of —1 is returned and errno is set to indicate the 
error. 
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NAME 

ecvt, fcvt, gcvt — convert floating-point number to string 
SYNOPSIS 

char *ecvt (value, ndigit, decpt, sign) 

double value; 

int ndigit, * decpt, *sign; 

char *fcvt (value, ndigit, decpt, sign) 

double value; 

int ndigit, *decpt, *sign; 

char *gcvt (value, ndigit, buf) 
double value; 
int ndigit; 
char *buf; 

DESCRIPTION 

ecvt converts value to a null-terminated string of ndigit digits and returns a 
pointer thereto. The high-order digit is non-zero, unless the value is zero. The 
low-order digit is rounded. The position of the decimal point relative to the 
beginning of the string is stored indirectly through decpt (negative means to the 
left of the returned digits). The decimal point is not included in the returned 
string. If the sign of the result is negative, the word pointed to by sign is non- 
zero, otherwise it is zero. 

Fcvt is identical to ecvt, except that the correct digit has been rounded for printf 
"%f" (FORTRAN F-format) output of the number of digits specified by ndigit. 

Gcvt converts the value to a null-terminated string in the array pointed to by buf 
and returns buf. It attempts to produce ndigit significant digits in FORTRAN F- 
format if possible, otherwise E-format, ready for printing. A minus sign, if there 
is one, or a decimal point will be included as part of the returned string. 
Trailing zeros are suppressed. 

SEE ALSO 

printf(3S). 

BUGS 

The values returned by ecvt and fcvt point to a single static data array whose 
content is overwritten by each call. 
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NAME 

end, etext, edata — last locations in program 

SYNOPSIS 

extern end; 
extern etext; 
extern edata; 

DESCRIPTION 

These names refer neither to routines nor to locations with interesting contents. 
The address of etext is the first address above the program text, edata above the 
initialized data region, and end above the uninitialized data region. 

When execution begins, the program break (the first location beyond the data) 
coincides with end, but the program break may be reset by the routines of 
brk( 2), malloc( 3C), standard input/output [stdio( 3S)], the profile (— p) option of 
cc( 1), and so on. Thus, the current value of the program break should be deter- 
mined by sbrk (char *)(0) [see brk( 2)]. 

SEE ALSO 

cc(l), brk(2), malloc(3C), stdio(3S). 
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NAME 

fclose, fflush — close or flush a stream 
SYNOPSIS 

#include <stdio.h> 

int fclose (stream) 

FILE *stream; 

int fflush (stream) 

FILE *stream; 

DESCRIPTION 

fclose causes any buffered data for the named stream to be written out, and the 
stream to be closed. 

fclose is performed automatically for all open files upon calling exit (2). 

Fflush causes any buffered data for the named stream to be written to that file. 
The stream remains open. 

SEE ALSO 

close(2), exit(2), fopen(3S), setbuf(3S), stdio(3S). 

DIAGNOSTICS 

These functions return 0 for success, and EOF if any error (such as trying to 
write to a file that has not been opened for writing) was detected. 



276 




FERROR(3S) 



(C Programming Language Utilities) 



FERROR(3S) 



NAME 

ferror, feof, clearerr, fileno — stream status inquiries 
SYNOPSIS 

#include <stdio.h> 

int ferror (stream) 

FILE *stream; 

int feof (stream) 

FILE ^stream; 

void clearerr (stream) 

FILE ^stream; 

int fileno (stream) 

FILE ^stream; 

DESCRIPTION 

ferror returns non-zero when an I/O error has previously occurred reading from 
or writing to the named stream, otherwise zero. 

Feof returns non-zero when EOF has previously been detected reading the 
named input stream, otherwise zero. 

Clearerr resets the error indicator and EOF indicator to zero on the named 
stream. 

Fileno returns the integer file descriptor associated with the named stream; see 
open (2). 

NOTES 

All these functions are implemented as macros; they cannot be declared or rede- 
clared. 

SEE ALSO 

open(2), fopen(3S), stdio(3S). 
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NAME 

fopen, freopen, fdopen — open a stream 
SYNOPSIS 

#include <stdio.h> 

FILE *fopen (filename, type) 
char *filename, *type; 

FILE *freopen (filename, type, stream) 
char *Hlename, *type; 

FILE *stream; 

FILE *fdopen (Hides, type) 
int Hides; 
char *type; 

DESCRIPTION 

fopen opens the file named by filename and associates a stream with it. fopen 
returns a pointer to the FILE structure associated with the stream. 

Filename points to a character string that contains the name of the file to be 
opened. 

Type is a character string having one of the following values: 

"r" open for reading 

"w" truncate or create for writing 

"a” append; open for writing at end of file, or create for writing 

"r+" open for update (reading and writing) 

"w+" truncate or create for update 

"a+" append; open or create for update at end-of-file 

Freopen substitutes the named file in place of the open stream. The original 
stream is closed, regardless of whether the open ultimately succeeds. Freopen 
returns a pointer to the FILE structure associated with stream. 

Freopen is typically used to attach the preopened streams associated with stdin, 
stdout and stderr to other files. 

Fdopen associates a stream with a file descriptor. File descriptors are obtained 
from open, dup, creat, or pipe (2), which open files but do not return pointers to a 
FILE structure stream. Streams are necessary input for many of the Section 3S 
library routines. The type of stream must agree with the mode of the open file. 

When a file is opened for update, both input and output may be done on the 
resulting stream. However, output may not be directly followed by input 
without an intervening fseek or rewind, and input may not be directly followed 
by output without an intervening fseek, rewind, or an input operation which 
encounters end-of-file. 

When a file is opened for append (i.e., when type is "a" or "a+' , ) / it is impossible 
to overwrite information already in the file. Fseek may be used to reposition the 
file pointer to any position in the file, but when output is written to the file, the 
current file pointer is disregarded. All output is written at the end of the file and 
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causes the file pointer to be repositioned at the end of the output. If two 
separate processes open the same file for append, each process may write freely 
to the file without fear of destroying output being written by the other. The 
output from the two processes will be intermixed in the file in the order in 
which it is written. 

SEE ALSO 

creat(2), dup(2), open(2), pipe(2), fclose(3S), fseek(3S), stdio(3S). 

DIAGNOSTICS 

fopen, fdopen, and f reopen return a NULL pointer on failure. 
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NAME 

fpgetround, fpsetround, fpgetmask, fpsetmask, fpgetsticky, fpsetsticky — IEEE 
floating point environment control 

SYNOPSIS 

#include <ieeefp.h> 
typedef enum { 

FP_RN=0, /* round to nearest */ 

FPRP, /* round to plus */ 

FP_RM, /* round to minus */ 

FP RZ, /* round to zero (truncate) */ 

} fprnd; 

fp rnd fpgetroundO; 

fp rnd fpsetround(rnd dir) 
fprnd rnd dir; 

#define fp except int 

#define FP X INV 0x10 /* invalid operation exception*/ 

#define FP X OFL 0x08 /* overflow exception*/ 

#define FP X UFL 0x04 /* underflow exception*/ 

#deflne FP X DZ 0x02 /* divide-by-zero exception*/ 

#define FP X IMP 0x01 /* imprecise (loss of precision)*/ 

fp except fpgetmaskO; 

fp except fpsetmask(mask); 

^ except mask; 

fp except fpgetstickyO; 

fp except fpsetsticky(sticky); 
fp except sticky; 

DESCRIPTION 

There are five floating point exceptions: divide-by-zero, overflow, underflow, 
imprecise (inexact) result, and invalid operation. When a floating point excep- 
tion occurs, the corresponding sticky bit is set (1), and if the mask bit is enabled 
(1), the trap takes place. These routines let the user change the behavior on 
occurrence of any of these exceptions, as well as change the rounding mode for 
floating point operations. 

fpgetround () returns the current rounding mode. 
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fpgetsticky () returns the current exception sticky flags. 

fpsetstickyQ sets (clears) the exception sticky flags and returns the previous set- 
ting. 

The default environment on the 3B computer family is: 

Rounding mode set to nearest(FPRN), 

Divide-by-zero, 

Floating point overflow, and 
Invalid operation traps enabled. 

SEE ALSO 

isnan(3C). 

WARNINGS 

fpsetstickyQ modifies all sticky flags. fpsetmaskQ changes all mask bits. 

Both C and F 77 require truncation (round to zero) for floating point to integral 
conversions. The current rounding mode has no effect on these conversions. 

CAVEATS 

One must clear the sticky bit to recover from the trap and to proceed. If the 
sticky bit is not cleared before the next trap occurs, a wrong exception type may 
be signaled. 

For the same reason, when calling fpsetmaskQ the user should make sure that the 
sticky bit corresponding to the exception being enabled is cleared. 
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NAME 

fread, fwrite — binary input/output 
SYNOPSIS 

#include <stdio.h> 

#include <sys/types.h> 

int fread (ptr, size, nitems, stream) 
char *ptr; 
int nitems; 
sizet size; 

FILE *stream; 

int fwrite (ptr, size, nitems, stream) 
char *ptr; 
int nitems; 
size t size; 

FILE ^stream; 

DESCRIPTION 

fread copies, into an array pointed to by ptr, nitems items of data from the 
named input stream, where an item of data is a sequence of bytes (not neces- 
sarily terminated by a null byte) of length size . fread stops appending bytes if 
an end-of-file or error condition is encountered while reading stream, or if nitems 
items have been read, fread leaves the file pointer in stream, if defined, pointing 
to the byte following the last byte read if there is one. fread does not change 
the contents of stream. 

fwrite appends at most nitems items of data from the array pointed to by ptr to 
the named output stream, fwrite stops appending when it has appended nitems 
items of data or if an error condition is encountered on stream, fwrite does not 
change the contents of the array pointed to by ptr. 

The argument size is typically sizeof(*ptr) where the pseudo-function sizeof 
specifies the length of an item pointed to by ptr. If ptr points to a data type 
other than char it should be cast into a pointer to char. 

SEE ALSO 

read(2), write(2), fopen(3S), getc(3S), gets(3S), printf(3S), putc(3S), puts(3S), 
scanf(3S), stdio(3S). 

DIAGNOSTICS 

fread and fwrite return the number of items read or written. If nitems is non- 
positive, no characters are read or written and 0 is returned by both fread and 
fwrite. 
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NAME 

frexp, ldexp, modf — manipulate parts of floating-point numbers 
SYNOPSIS 

double frexp (value, eptr) 
double value; 
int *eptr; 

double ldexp (value, exp) 
double value; 
int exp; 

double modf (value, iptr) 
double value, *iptr; 

DESCRIPTION 

Every non-zero number can be written uniquely as x* 2 n , where the "mantissa" 
(fraction) x is in the range 0.5 < \x\ < 1.0, and the "exponent" n is an integer. 
frexp returns the mantissa of a double value, and stores the exponent indirectly 
in the location pointed to by eptr . If value is zero, both results returned by frexp 
are zero. 

Ldexp returns the quantity value* 2 exp . 

Modf returns the signed fractional part of value and stores the integral part 
indirectly in the location pointed to by iptr. 

DIAGNOSTICS 

If ldexp would cause overflow, ±HUGE (defined in <math.h> ) is returned 
(according to the sign of value), and errno is set to ERANGE. 

If ldexp would cause underflow, zero is returned and errno is set to ERANGE. 
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NAME 

fseek, rewind, ftell — reposition a file pointer in a stream 
SYNOPSIS 

#include <stdio.h> 

int fseek (stream, offset, ptrname) 

FILE *stream; 
long offset; 
int ptrname; 

void rewind (stream) 

FILE *stream; 

long ftell (stream) 

FILE *stream; 

DESCRIPTION 

fseek sets the position of the next input or output operation on the stream. The 
new position is at the signed distance offset bytes from the beginning, from the 
current position, or from the end of the file, according as ptrname has the value 
0, 1, or 2. 

Rewind(stream) is equivalent to fseek(stream, 0L, 0), except that no value is 
returned. 

fseek and rewind undo any effects of ungetc( 3S). 

After fseek or rewind, the next operation on a file opened for update may be 
either input or output. 

Ftell returns the offset of the current byte relative to the beginning of the file 
associated with the named stream. 

SEE ALSO 

lseek(2), fopen(3S), popen(3S), stdio(3S), ungetc(3S). 

DIAGNOSTICS 

fseek returns non-zero for improper seeks, otherwise zero. An improper seek 
can be, for example, an fseek done on a file that has not been opened via fopen ; 
in particular, fseek may not be used on a terminal, or on a file opened via 
popen( 3S). 

WARNING 

Although on the UNIX system an offset returned by ftell is measured in bytes, 
and it is permissible to seek to positions relative to that offset, portability to 
non-UNIX systems requires that an offset be used by fseek directly. Arithmetic 
may not meaningfully be performed on such an offset, which is not necessarily 
measured in bytes. 
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NAME 

ftw — walk a file tree 

SYNOPSIS 

#include <ftw.h> 

int ftw (path, fn, depth) 
char *path; 
int (*fn) ( ); 
int depth; 

DESCRIPTION 

ftw recursively descends the directory hierarchy rooted in path. For each object 
in the hierarchy, ftw calls fn, passing it a pointer to a null-terminated character 
string containing the name of the object, a pointer to a stat structure [see stat( 2)] 
containing information about the object, and an integer. Possible values of the 
integer, defined in the <ftw.h> header file, are FTW F for a file, FTW D for a 
directory, FTWDNR for a directory that cannot be read, and FTW NS for an 
object for which stat could not successfully be executed. If the integer is 
FTW DNR, descendants of that directory will not be processed. If the integer is 
FTW NS, the stat structure will contain garbage. An example of an object that 
would cause FTW NS to be passed to fn would be a file in a directory with read 
but without execute (search) permission. 

ftw visits a directory before visiting any of its descendants. 

The tree traversal continues until the tree is exhausted, an invocation of fn 
returns a nonzero value, or some error is detected within ftw (such as an I/O 
error). If the tree is exhausted, ftw returns zero. If fn returns a nonzero value, 
ftw stops its tree traversal and returns whatever value was returned by fn . If ftw 
detects an error, it returns —1, and sets the error type in errno. 

ftw uses one file descriptor for each level in the tree. The depth argument limits 
the number of file descriptors so used. If depth is zero or negative, the effect is 
the same as if it were 1. Depth must not be greater than the number of file 
descriptors currently available for use. ftw will run more quickly if depth is at 
least as large as the number of levels in the tree. 

SEE ALSO 

stat(2), malloc(3C). 

BUGS 

Because ftw is recursive, it is possible for it to terminate with a memory fault 
when applied to very deep file structures. 

CAVEAT 

ftw uses malloc{ 3C) to allocate dynamic storage during its operation. If ftw is 
forcibly terminated, such as by longjmp being executed by fn or an interrupt rou- 
tine, ftw will not have a chance to free that storage, so it will remain per- 
manently allocated. A safe way to handle interrupts is to store the fact that an 
interrupt has occurred, and arrange to have fn return a nonzero value at its next 
invocation. 
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NAME 

getc, getchar, fgetc, getw — get character or word from a stream 
SYNOPSIS 

#include <stdio.h> 

int getc (stream) 

FILE ^stream; 

int getchar () 

int fgetc (stream) 

FILE *stream; 

int getw (stream) 

FILE *stream; 

DESCRIPTION 

getc returns the next character (i.e., byte) from the named input stream, as an 
integer. It also moves the file pointer, if defined, ahead one character in stream, 
getchar is defined as getc(stdin). getc and getchar are macros. 

Fgetc behaves like getc, but is a function rather than a macro. Fgetc runs more 
slowly than getc, but it takes less space per invocation and its name can be 
passed as an argument to a function. 

Getw returns the next word (i.e., integer) from the named input stream. Getw 
increments the associated file pointer, if defined, to point to the next word. The 
size of a word is the size of an integer and varies from machine to machine. 
Getw assumes no special alignment in the file. 

SEE ALSO 

fclose(3S), ferror(3S), fopen(3S), fread(3S), gets(3S), putc(3S), scanf(3S), 
stdio(3S). 

DIAGNOSTICS 

These functions return the constant EOF at end-of-file or upon an error. Because 
EOF is a valid integer, ferror( 3S) should be used to detect getw errors. 

WARNING 

If the integer value returned by getc, getchar, or fgetc is stored into a character 
variable and then compared against the integer constant EOF, the comparison 
may never succeed, because sign-extension of a character on widening to integer 
is machine-dependent. 

CAVEATS 

Because it is implemented as a macro, getc evaluates a stream argument more 
than once. In particular, getc(*f++) does not work sensibly. Fgetc should be 
used instead. 

Because of possible differences in word length and byte ordering, files written 
using putw are machine-dependent, and may not be read using getw on a 
different processor. 



286 




GETCWD(3C) 



(C Programming Language Utilities) 



GETCWD(3C) 



NAME 

getcwd — get path-name of current working directory 
SYNOPSIS 

char *getcwd (buf, size) 
char *buf; 
int size; 

DESCRIPTION 

getcwd returns a pointer to the current directory path name. The value of size 
must be at least two greater than the length of the path-name to be returned. 

If buf is a NULL pointer, getcwd will obtain size bytes of space using malloc( 3C). 
In this case, the pointer returned by getcwd may be used as the argument in a 
subsequent call to free. 

The function is implemented by using popen( 3S) to pipe the output of the 
pwd( 1) command into the specified string space. 

EXAMPLE 

void exit(), perrorQ; 



if ((cwd = getcwd((char *)NULL, 64)) — NULL) { 
perrorf'pwd"); 

^ exit(2); 

printf("%s\n", cwd); 

SEE ALSO 

malloc(3C), popen(3S). 

pwd(l) in the User's Reference Manual 

DIAGNOSTICS 

Returns NULL with errno set if size is not large enough, or if an error occurs in a 
lower-level function. 
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NAME 

getenv — return value for environment name 
SYNOPSIS 

char *getenv (name) 
char *name; 

DESCRIPTION 

getenv searches the environment list [see environ(5)\ for a string of the form 
name=value, and returns a pointer to the value in the current environment if 
such a string is present, otherwise a NULL pointer. 

SEE ALSO 

exec(2), putenv(3C), environ(5). 



288 




GETGRENT(3C) 



(C Programming Language Utilities) 



GETGRENT(3C) 



NAME 

getgrent, getgrgid, getgrnam, setgrent, endgrent, fgetgrent — get group file entry 

SYNOPSIS 

#include <grp.h> 

struct group *getgrent ( ) 

struct group *getgrgid (gid) 
int gid; 

struct group *getgrnam (name) 
char *name; 

void setgrent ( ) 
void endgrent ( ) 

struct group *fgetgrent (f) 

FILE *f; 

DESCRIPTION 

getgrent , getgrgid and getgrnam each return pointers to an object with the fol- 
lowing structure containing the broken-out fields of a line in the /etc/group file. 
Each line contains a "group" structure, defined in the <grp.h> header file. 

struct group { 

char *gr_name; /* the name of the group */ 

char *gr_passwd; /* the encrypted group password */ 

int gr_gid; /* the numerical group ID */ 

char **gr_mem; /* vector of pointers to member names */ 

getgrent when first called returns a pointer to the first group structure in the file; 
thereafter, it returns a pointer to the next group structure in the file; so, succes- 
sive calls may be used to search the entire file. Getgrgid searches from the 
beginning of the file until a numerical group id matching gid is found and 
returns a pointer to the particular structure in which it was found. Getgrnam 
searches from the beginning of the file until a group name matching name is 
found and returns a pointer to the particular structure in which it was found. If 
an end-of-file or an error is encountered on reading, these functions return a 
NULL pointer. 

A call to setgrent has the effect of rewinding the group file to allow repeated 
searches. Endgrent may be called to close the group file when processing is 
complete. 

Fgetgrent returns a pointer to the next group structure in the stream /, which 
matches the format of /etc/group. 

FILES 

/etc/group 
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SEE ALSO 

getlogin(3C), getpwent(3C), group(4). 

DIAGNOSTICS 

A NULL pointer is returned on EOF or error. 

WARNING 

The above routines use <stdio.h>, which causes them to increase the size of 
programs, not otherwise using standard I/O, more than might be expected. 

CAVEAT 

All information is contained in a static area, so it must be copied if it is to be 
saved. 
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NAME 

getlogin — get login name 

SYNOPSIS 

char *getlogin ( ); 

DESCRIPTION 

getlogin returns a pointer to the login name as found in /etc/utmp. It may be 
used in conjunction with getpwnam to locate the correct password file entry 
when the same user ID is shared by several login names. 

If getlogin is called within a process that is not attached to a terminal, it returns 
a NULL pointer. The correct procedure for determining the login name is to call 
cuserid, or to call getlogin and if it fails to call getpwuid , 

FILES 

/etc/utmp 
SEE ALSO 

cuserid(3S), getgrent(3C), getpwent(3C), utmp(4). 

DIAGNOSTICS 

Returns the NULL pointer if name is not found. 

CAVEAT 

The return values point to static data whose content is overwritten by each call. 
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NAME 

getopt — get option letter from argument vector 
SYNOPSIS 

int getopt (argc, argv, optstring) 
int argc; 

char **argv, *opstring; 

extern char *optarg; 
extern int optind, opterr; 

DESCRIPTION 

getopt returns the next option letter in argv that matches a letter in optstring. It 
supports all the rules of the command syntax standard (see intro (1)). So all new 
commands will adhere to the command syntax standard, they should use 
getopts( 1) or getopt ( 3C) to parse positional parameters and check for options that 
are legal for that command. 

optstring must contain the option letters the command using getopt will recog- 
nize; if a letter is followed by a colon, the option is expected to have an argu- 
ment, or group of arguments, which must be separated from it by white space. 

optarg is set to point to the start of the option-argument on return from getopt. 

getopt places in optind the argv index of the next argument to be processed, 
optind is external and is initialized to 1 before the first call to getopt. 

When all options have been processed (i.e., up to the first non-option argument), 
getopt returns —1. The special option " — " may be used to delimit the end of 
the options; when it is encountered, — 1 will be returned, and " — " will be 
skipped. 

DIAGNOSTICS 

getopt prints an error message on standard error and returns a question mark (?) 
when it encounters an option letter not included in optstring or no option- 
argument after an option that expects one. This error message may be disabled 
by setting opterr to 0. 

EXAMPLE 

The following code fragment shows how one might process the arguments for a 
command that can take the mutually exclusive options a and b, and the option 
o, which requires an option-argument: 



main (argc, 
int argc ; 
char **argv; 
{ 

int c ; 
extern 
extern 



argv ) 



char *optarg; 
int optind; 
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while ( ( c = getopt(argc, argv, "abo: " )) != -1) 

switch (c) { 

case ' a ' : 

if (bflg) 

errf lg++ ; 

else 

af lg++ ; 
break ; 
case ' b ' : 

if (aflg) 

errf lg+ + ; 

else 

bproc ( ); 

break ; 
case 'o': 

ofile = optarg; 
break ; 
case 1 ? ' : 

errf lg + + ; 

} 

if ( err f lg ) { 

( void ) f pr intf ( stderr , "usage: . . . "); 

exit ( 2 ) ; 

} 

for ( ; optind < argc ; optind++) { 

if ( acces s ( argv [ optind ] , 4)) { 



} 

This code will accept any of the following as equivalent: 



cmd 


-a 


-b -o " xxx z yy" file 


cmd 


-a 


-b -o "xxx z yy" -- file 


cmd 


-ab 


-o xxx , z , yy file 


cmd 


-ab 


-o "xxx z yy" file 


cmd 


-o 


xxx,z,yy -b -a file 



WARNING 

Although the following command syntax rule (see intro ( 1)) relaxations are per- 
mitted under the current implementation, they should not be used because they 
may not be supported in future releases of the system. As in the EXAMPLE sec- 
tion above, a and b are options, and the option o requires an option-argument: 

cmd — aboxxx file (Rule 5 violation: options with 

option-arguments must not be grouped with other options) 
cmd — ab — oxxx file (Rule 6 violation: there must be 

white space after an option that takes an option-argument) 

Changing the value of the variable optind, or calling get opt with different values 
of argv, may lead to unexpected results. 

SEE ALSO 

getopts(l), intro(l) in the User's Reference Manual. 
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NAME 

getpass — read a password 
SYNOPSIS 

char *getpass (prompt) 
char *prompt; 

DESCRIPTION 

getpass reads up to a newline or EOF from the file /dev/tty, after prompting on 
the standard error output with the null-terminated string prompt and disabling 
echoing. A pointer is returned to a null-terminated string of at most 8 charac- 
ters. If /dev/tty cannot be opened, a NULL pointer is returned. An interrupt 
will terminate input and send an interrupt signal to the calling program before 
returning. 

FILES 

/dev/tty 

WARNING 

The above routine uses <stdio.h>, which causes it to increase the size of pro- 
grams not otherwise using standard I/O, more than might be expected. 

CAVEAT 

The return value points to static data whose content is overwritten by each call. 
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NAME 

getpw — get name from UID 
SYNOPSIS 

int getpw (uid, buf) 
int uid; 
char *buf; 

DESCRIPTION 

getpw searches the password file for a user id number that equals uid, copies the 
line of the password file in which uid was found into the array pointed to by 
buf, and returns 0. getpw returns non-zero if uid cannot be found. 

This routine is included only for compatibility with prior systems and should not 
be used; see getpw ent( 3C) for routines to use instead. 

FILES 

/etc/passwd 
SEE ALSO 

getpwent(3C), passwd(4). 

DIAGNOSTICS 

getpw returns non-zero on error. 

WARNING 

The above routine uses <stdio.h>, which causes it to increase, more than 
might be expected, the size of programs not otherwise using standard I/O. 
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NAME 

getpwent, getpwuid, getpwnam, setpwent, endpwent, fgetpwent — get password 
file entry 

SYNOPSIS 

#include <pwd.h> 
struct passwd *getpwent ( ) 

struct passwd *getpwuid (uid) 
int uid; 

struct passwd *getpwnam (name) 
char *name; 

void setpwent ( ) 
void endpwent ( ) 

struct passwd *fgetpwent (f) 

FILE *f; 

DESCRIPTION 

getpwent , getpwuid and getpwnam each returns a pointer to an object with the 
following structure containing the broken-out fields of a line in the /etc/passwd 
file. Each line in the file contains a "passwd" structure, declared in the 
<pwd.h> header file: 

struct passwd { 

char *pw_name; 
char *pw_passwd; 
int pwuid; 

int pw_gid; 

char *pw_age; 
char *pw_comment; 
char *pw_gecos; 
char *pw_dir; 
char *pw shell; 

}; 

This structure is declared in <pwd.h> so it is not necessary to redeclare it. 

The fields have meanings described in passwd (4). 

getpwent when first called returns a pointer to the first passwd structure in the 
file; thereafter, it returns a pointer to the next passwd structure in the file; so 
successive calls can be used to search the entire file. Getpwuid searches from the 
beginning of the file until a numerical user id matching uid is found and returns 
a pointer to the particular structure in which it was found. Getpwnam searches 
from the beginning of the file until a login name matching name is found, and 
returns a pointer to the particular structure in which it was found. If an end-of- 
file or an error is encountered on reading, these functions return a NULL pointer. 

A call to setpwent has the effect of rewinding the password file to allow repeated 
searches. Endpwent may be called to close the password file when processing is 
complete. 
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Fgetpwent returns a pointer to the next passwd structure in the stream /, which 
matches the format of /etc/passwd. 

FILES 

/etc/passwd 
SEE ALSO 

getlogin(3C), getgrent(3C), passwd(4). 

DIAGNOSTICS 

A NULL pointer is returned on EOF or error. 

WARNING 

The above routines use <stdio.h>, which causes them to increase the size of 
programs, not otherwise using standard I/O, more than might be expected. 

CAVEAT 

All information is contained in a static area, so it must be copied if it is to be 
saved. 
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NAME 

gets, fgets — get a string from a stream 
SYNOPSIS 

#include <stdio.h> 

char *gets (s) 
char *s; 

char *fgets (s, n, stream) 
char *s; 
int n; 

FILE *stream; 

DESCRIPTION 

gets reads characters from the standard input stream, stdin, into the array 
pointed to by s, until a new-line character is read or an end-of-file condition is 
encountered. The new-line character is discarded and the string is terminated 
with a null character. 

Fgets reads characters from the stream into the array pointed to by s, until n — 1 
characters are read, or a new-line character is read and transferred to s, or an 
end-of-file condition is encountered. The string is then terminated with a null 
character. 

SEE ALSO 

ferror(3S), fopen(3S), fread(3S), getc(3S), scanf(3S), stdio(3S). 

DIAGNOSTICS 

If end-of-file is encountered and no characters have been read, no characters are 
transferred to s and a NULL pointer is returned. If a read error occurs, such as 
trying to use these functions on a file that has not been opened for reading, a 
NULL pointer is returned. Otherwise s is returned. 
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NAME 

getut: getutent, getutid, getutline, pututline, setutent, endutent, utmpname — 
access utmp file entry 

SYNOPSIS 

#include <utmp.h> 
struct utmp *getutent ( ) 

struct utmp *getutid (id) 
struct utmp *id; 

struct utmp *getutline (line) 
struct utmp *line; 

void pututline (utmp) 
struct utmp *utmp; 

void setutent ( ) 
void endutent ( ) 

void utmpname (file) 
char *file; 



DESCRIPTION 

getutent, getutid and getutline each return a pointer to a structure of the fol- 
lowing type: 



struct utmp { 

char ut_user[8]; 

char ut_id[4]; 

char ut_line[12]; 

short ut_pid; 

short ut_type; 

struct exit_status { 
short e_termination; 

short e_exit; 

} utexit; 

time_t ut_time; 



/* User login name */ 

/* /etc/inittab id (usually line #) */ 
/* device name (console, lnxx) */ 

/* process id */ 

/* type of entry */ 

/* Process termination status */ 

/* Process exit status */ 

/* The exit status of a process 
* marked as DEADPROCESS. */ 

/* time entry was made */ 



getutent reads in the next entry from a utmp- like file. If the file is not already 
open, it opens it. If it reaches the end of the file, it fails. 

getutid searches forward from the current point in the utmp file until it finds an 
entry with a utjype matching id—>ut_type if the type specified is RUN LVL, 
BOOTTIME, OLDTIME or NEWTIME. If the type specified in id is 
INIT PROCESS, LOGIN JPROCESS, USER_PROCESS or DEAD_PROCESS, then getutid 
will return a pointer to the first entry whose type is one of these four and whose 
utjd field matches id—>ut_id. If the end of file is reached without a match, it 
fails. 
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getutline searches forward from the current point in the utmp file until it finds an 
entry of the type LOGIN_PROCESS or USER_PROCESS which also has a utjine 
string matching the line— > utjine string. If the end of file is reached without a 
match, it fails. 

Pututline writes out the supplied utmp structure into the utmp file. It uses 
getutid to search forward for the proper place if it finds that it is not already at 
the proper place. It is expected that normally the user of pututline will have 
searched for the proper entry using one of the getut routines. If so, pututline 
will not search. If pututline does not find a matching slot for the new entry, it 
will add a new entry to the end of the file. 

Setutent resets the input stream to the beginning of the file. This should be 
done before each search for a new entry if it is desired that the entire file be 
examined. 

Endutent closes the currently open file. 

Utmpname allows the user to change the name of the file examined, from 
/etc/utmp to any other file. It is most often expected that this other file will be 
/etc/wtmp. If the file does not exist, this will not be apparent until the first 
attempt to reference the file is made. Utmpname does not open the file. It just 
closes the old file if it is currently open and saves the new file name. 

FILES 

/etc/utmp 

/etc/wtmp 

SEE ALSO 

ttyslot(3C), utmp(4). 

DIAGNOSTICS 

A NULL pointer is returned upon failure to read, whether for permissions or 
having reached the end of file, or upon failure to write. 

NOTES 

The most current entry is saved in a static structure. Multiple accesses require 
that it be copied before further accesses are made. Each call to either getutid or 
getutline sees the routine examine the static structure before performing more 
I/O. If the contents of the static structure match what it is searching for, it looks 
no further. For this reason to use getutline to search for multiple occurrences, it 
would be necessary to zero out the static after each success, or getutline would 
just return the same pointer over and over again. There is one exception to the 
rule about removing the structure before further reads are done. The implicit 
read done by pututline (if it finds that it is not already at the correct place in the 
file) will not hurt the contents of the static structure returned by the getutent, 
getutid or getutline routines, if the user has just modified those contents and 
passed the pointer back to pututline. 

These routines use buffered standard I/O for input, but pututline uses an 
unbuffered non-standard write to avoid race conditions between processes trying 
to modify the utmp and wtmp files. 
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NAME 

hsearch, hcreate, hdestroy — manage hash search tables 
SYNOPSIS 

#include <search.h> 

ENTRY *hsearch (item, action) 

ENTRY item; 

ACTION action; 

int hcreate (nel) 
unsigned nel; 

void hdestroy ( ) 

DESCRIPTION 

hsearch is a hash-table search routine generalized from Knuth (6.4) Algorithm D. 
It returns a pointer into a hash table indicating the location at which an entry 
can be found. Item is a structure of type ENTRY (defined in the <search.h> 
header file) containing two pointers: item. key points to the comparison key, and 
item.data points to any other data to be associated with that key. (Pointers to 
types other than character should be cast to pointer-to-character.) Action is a 
member of an enumeration type ACTION indicating the disposition of the entry 
if it cannot be found in the table. ENTER indicates that the item should be 
inserted in the table at an appropriate point. FIND indicates that no entry 
should be made. Unsuccessful resolution is indicated by the return of a NULL 
pointer. 

Hcreate allocates sufficient space for the table, and must be called before hsearch 
is used. Nel is an estimate of the maximum number of entries that the table will 
contain. This number may be adjusted upward by the algorithm in order to 
obtain certain mathematically favorable circumstances. 

Hdestroy destroys the search table, and may be followed by another call to 
hcreate. 

NOTES 

hsearch uses open addressing with a multiplicative hash function. However, its 
source code has many other options available which the user may select by 
compiling the hsearch source with the following symbols defined to the prepro- 
cessor: 

DIV Use the remainder modulo table size as the hash function 
instead of the multiplicative algorithm. 

USCR Use a User Supplied Comparison Routine for ascertaining 
table membership. The routine should be named hcompar 
and should behave in a mannner similar to strcmp [see 
string( 3C)]. 

CHAINED Use a linked list to resolve collisions. If this option is 
selected, the following other options become available. 

START Place new entries at the beginning of the linked 
list (default is at the end). 
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SORTUP Keep the linked list sorted by key in ascending 
order. 

SORTDOWN Keep the linked list sorted by key in descending 
order. 

Additionally, there are preprocessor flags for obtaining debugging printout 
(— ' DDEBUG) and for including a test driver in the calling routine (— DDRIVER). 
The source code should be consulted for further details. 

EXAMPLE 

The following example will read in strings followed by two numbers and store 
them in a hash table, discarding duplicates. It will then read in strings and find 
the matching entry in the hash table and print it out. 

#include <stdio.h> 

#include <search.h> 



struct info { 

int age, room; 



# define NUM_EMPL 



/* this is the info stored in the table */ 

/* other than the key. */ 

5000 /* # of elements in search table */ 



main( ) 

{ 

/* space to store strings */ 
char string_space[NUM_EMPL*20]; 

/* space to store employee info */ 
struct info info_space[NUM_EMPL]; 

/* next avail space in string_space */ 
char *strj3tr = string_space; 

/* next avail space in info_space */ 
struct info *info_ptr = info_space; 
ENTRY item, *found_item, *hsearch( ); 
/* name to look for in table */ 
char name_to_find[30]; 
int i = 0; 



/* create table */ 

(void) hcreate(NUM EMPL); 

while (scanf("%s%d%d", str_ptr, &info_ptr— > age, 

&info_ptr— > room) != EOF && i++ < NUM EMPL) { 

/* put info in structure, and structure in item */ 

item, key = strjstr; 

item. data — (char *)info_ptr; 

strjstr += strlen(str_ptr) + 1; 

infoj?tr++; 

/* put item into table */ 

(void) hsearch(item, ENTER); 



/* access table */ 



302 




HSEARCH(3C) (C Programming Language Utilities) HSEARCH(3C) 

item.key = name_to_find; 

while (scanf("%s", item.key) != EOF) { 

if ((foundjtem = hsearch(item, FIND)) != NULL) { 

/* if item is in the table */ 

(void)printf("found %s, age = %d, room = %d\n", 
foundjtem— > key, 

((struct info *)found_item—> data)— > age, 

((struct info *)found_item—> data)— > room); 

} else { 

(void)printf("no such employee %s\n", 
nametofind) 




} 

SEE ALSO 

bsearch(3C), lsearch(3C), malloc(3C), malloc(3X), string(3C), tsearch(3C). 
DIAGNOSTICS 

hsearch returns a NULL pointer if either the action is FIND and the item could 
not be found or the action is ENTER and the table is full. 

Hcreate returns zero if it cannot allocate sufficient space for the table. 

WARNING 

hsearch and hcreate use malloc( 3C) to allocate space. 

CAVEAT 

Only one hash search table may be active at any given time. 
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NAME 

isnan: isnand, isnanf — test for floating point NaN (Not-A-Number) 

SYNOPSIS 

#include <ieeefp.h> 

int isnand (dsrc) 
double dsrc; 

int isnanf (fsrc) 
float fsrc; 

DESCRIPTION 

isnand and isnanf return true (1) if the argument dsrc or fsrc is a NaN; otherwise 
they return false (0). 

Neither routine generates any exception, even for signaling NaNs. 
isnanfO is implemented as a macro included in <ieeefp.h>. 

SEE ALSO 

fpgetround(3C). 
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NAME 

13tol, ltol3 — convert between 3 -byte integers and long integers 
SYNOPSIS 

void 13tol (lp, cp, n) 
long *lp; 
char *cp; 
int n; 

void ltol3 (cp, lp, n) 
char *cp; 
long *lp; 
int n; 

DESCRIPTION 

l3tol converts a list of n three-byte integers packed into a character string 
pointed to by cp into a list of long integers pointed to by lp. 

Ltol3 performs the reverse conversion from long integers (lp) to three-byte 
integers (cp). 

These functions are useful for file-system maintenance where the block numbers 
are three bytes long. 

SEE ALSO 

fs(4). 

CAVEAT 

Because of possible differences in byte ordering, the numerical values of the long 
integers are machine-dependent. 
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NAME 

lockf — record locking on files 
SYNOPSIS 

#include <unistd.h> 



int lockf (fildes, function, size) 
long size; 

int fildes, function; 



DESCRIPTION 

The lockf command will allow sections of a file to be locked; advisory or manda- 
tory write locks depending on the mode bits of the file [see chmod( 2)]. Locking 
calls from other processes which attempt to lock the locked file section will 
either return an error value or be put to sleep until the resource becomes 
unlocked. All the locks for a process are removed when the process terminates. 
[See fcntl( 2) for more information about record locking.] 

Fildes is an open file descriptor. The file descriptor must have 0_WR0NLY or 
0_RDWR permission in order to establish lock with this function call. 

Function is a control value which specifies the action to be taken. The permis- 
sible values for function are defined in <unistd.h> as follows: 



#define FJJLOCK 0 

# define F_LOCK 1 

#define FTLOCK 2 

#define FTEST 3 



/* Unlock a previously locked section */ 

/* Lock a section for exclusive use */ 

/* Test and lock a section for exclusive use */ 
/* Test section for other processes locks */ 



All other values of function are reserved for future extensions and will result in 
an error return if not implemented. 

F TEST is used to detect if a lock by another process is present on the specified 
section. F LOCK and F TLOCK both lock a section of a file if the section is avail- 
able. FJJLOCK removes locks from a section of the file. 

Size is the number of contiguous bytes to be locked or unlocked. The resource 
to be locked starts at the current offset in the file and extends forward for a posi- 
tive size and backward for a negative size (the preceding bytes up to but not 
including the current offset). If size is zero, the section from the current offset 
through the largest file offset is locked (i.e., from the current offset through the 
present or any future end-of-file). An area need not be allocated to the file in 
order to be locked as such locks may exist past the end-of-file. 

The sections locked with F_LOCK or F TLOCK may, in whole or in part, contain 
or be contained by a previously locked section for the same process. When this 
occurs, or if adjacent sections occur, the sections are combined into a single sec- 
tion. If the request requires that a new element be added to the table of active 
locks and this table is already full, an error is returned, and the new section is 
not locked. 

F_LOCK and F_TLOCK requests differ only by the action taken if the resource is 
not available. FTLOCK will cause the calling process to sleep until the resource is 
available. F TLOCK will cause the function to return a —1 and set errno to 
[EACCES] error if the section is already locked by another process. 
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F_ULOCK requests may, in whole or in part, release one or more locked sections 
controlled by the process. When sections are not fully released, the remaining 
sections are still locked by the process. Releasing the center section of a locked 
section requires an additional element in the table of active locks. If this table is 
full, an [EDEADLK] error is returned and the requested section is not released. 

A potential for deadlock occurs if a process controlling a locked resource is put 
to sleep by accessing another process's locked resource. Thus calls to lockf or 
fcntl scan for a deadlock prior to sleeping on a locked resource. An error return 
is made if sleeping on the locked resource would cause a deadlock. 

Sleeping on a resource is interrupted with any signal. The alarm( 2) command 
may be used to provide a timeout facility in applications which require this 
facility. 

The lockf utility will fail if one or more of the following are true: 

[EBADF] 

Fildes is not a valid open descriptor. 

[EACCES] 

Cmd is FTLOCK or F TEST and the section is already locked by another 
process. 

[EDEADLK] 

Cmd is F LOCK and a deadlock would occur. Also the cmd is either 
F LOCK, F TLOCK, or F ULOCK and the number of entries in the lock 
table would exceed the number allocated on the system. 

[ECOMM] 

Fildes is on a remote machine and the link to that machine is no longer 
active. 



SEE ALSO 

chmod(2), close(2), creat(2), fcntl(2), intro(2), open(2), read(2), write(2). 
DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 
is returned and errno is set to indicate the error. 

WARNINGS 

Unexpected results may occur in processes that do buffering in the user address 
space. The process may later read/write data which is/was locked. The stan- 
dard I/O package is the most common source of unexpected buffering. 

Because in the future the variable errno will be set to EAGAIN rather than 
EACCES when a section of a file is already locked by another process, portable 
application programs should expect and test for either value. 

NAME 

lsearch, lfind — linear search and update 
SYNOPSIS 

#include <stdio.h> 

#include <search.h> 
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char *lsearch ((char *)key, (char *)base, nelp, sizeof(*key), compar) 
unsigned *nelp; 
int (*compar)( ); 

char *lfind ((char *)key, (char *)base, nelp, sizeof(*key), compar) 
unsigned *nelp; 
int (*compar)( ); 

DESCRIPTION 

Isearch is a linear search routine generalized from Knuth (6.1) Algorithm S, It 
returns a pointer into a table indicating where a datum may be found. If the 
datum does not occur, it is added at the end of the table. Key points to the 
datum to be sought in the table. Base points to the first element in the table. 
Nelp points to an integer containing the current number of elements in the 
table. The integer is incremented if the datum is added to the table. Compar is 
the name of the comparison function which the user must supply ( strcmp , for 
example). It is called with two arguments that point to the elements being com- 
pared. The function must return zero if the elements are equal and non-zero 
otherwise. 

Lfind is the same as Isearch except that if the datum is not found, it is not added 
to the table. Instead, a NULL pointer is returned. 

NOTES 

The pointers to the key and the element at the base of the table should be of 
type pointer-to-element, and cast to type pointer-to-character. 

The comparison function need not compare every byte, so arbitrary data may be 
contained in the elements in addition to the values being compared. 

Although declared as type pointer-to-character, the value returned should be 
cast into type pointer-to-element. 

EXAMPLE 

This fragment will read in less than TABSIZE strings of length less than ELSIZE 
and store them in a table, eliminating duplicates. 

#include <stdio.h> 

#include <search.h> 

# define TABSIZE 50 
# define ELSIZE 120 

char line[ELSIZE], tab[TABSIZE][ELSIZE], *lsearch( ); 
unsigned nel = 0; 
int strcmp( ); 
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while (fgets(line, ELSIZE, stdin) != NULL && 
nel < TABSIZE) 

(void) lsearch(line, (char *)tab, &nel, 
ELSIZE, strcmp); 



SEE ALSO 

bsearch(3C), hsearch(3C), string(3C), tsearch(3C). 

DIAGNOSTICS 

If the searched for datum is found, both Isearch and Ifind return a pointer to it. 
Otherwise, Ifind returns NULL and Isearch returns a pointer to the newly added 
element. 

BUGS 

Undefined results can occur if there is not enough room in the table to add a 
new item. 
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NAME 

malloc, free, realloc, calloc — main memory allocator 

SYNOPSIS 

char *malloc (size) 
unsigned size; 

void free (ptr) 
char *ptr; 

char *realloc (ptr, size) 
char *ptr; 
unsigned size; 

char *calloc (nelem, elsize) 
unsigned nelem, elsize; 

DESCRIPTION 

malloc and free provide a simple general-purpose memory allocation package. 
malloc returns a pointer to a block of at least size bytes suitably aligned for any 
use. 

The argument to free is a pointer to a block previously allocated by malloc ; after 
free is performed this space is made available for further allocation, but its con- 
tents are left undisturbed. 

Undefined results will occur if the space assigned by malloc is overrun or if some 
random number is handed to free. 

malloc allocates the first big enough contiguous reach of free space found in a 
circular search from the last block allocated or freed, coalescing adjacent free 
blocks as it searches. It calls sbrk [see brk( 2)] to get more memory from the 
system when there is no suitable space already free. 

Realloc changes the size of the block pointed to by ptr to size bytes and returns 
a pointer to the (possibly moved) block. The contents will be unchanged up to 
the lesser of the new and old sizes. If no free block of size bytes is available in 
the storage arena, then realloc will ask malloc to enlarge the arena by size bytes 
and will then move the data to the new space. 

Realloc also works if ptr points to a block freed since the last call of malloc , 
realloc , or calloc ; thus sequences of free, malloc and realloc can exploit the search 
strategy of malloc to do storage compaction. 

Calloc allocates space for an array of nelem elements of size elsize. The space is 
initialized to zeros. 

Each of the allocation routines returns a pointer to space suitably aligned (after 
possible pointer coercion) for storage of any type of object. 

SEE ALSO 

brk(2), malloc(3X). 

DIAGNOSTICS 

malloc, realloc and calloc return a NULL pointer if there is no available memory 
or if the arena has been detectably corrupted by storing outside the bounds of a 
block. When this happens the block pointed to by ptr may be destroyed. 
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NOTES 

Search time increases when many objects have been allocated; that is, if a pro- 
gram allocates but never frees, then each successive allocation takes longer. For 
an alternate, more flexible implementation, see malloc( 3X). 
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NAME 

memory: memccpy, memchr, memcmp, memcpy, memset — memory operations 
SYNOPSIS 

#include < memory .h> 

char *memccpy (si, s2, c, n) 
char *sl, *s2; 
int c, n; 

char *memchr (s, c, n) 
char *s; 
int c, n; 

int memcmp (si, s2, n) 
char *sl, *s2; 
int n; 

char *memcpy (si, s2, n) 
char *sl, *s2; 
int n; 

char *memset (s, c, n) 
char *s; 
int c, n; 

DESCRIPTION 

These functions operate as efficiently as possible on memory areas (arrays of 
characters bounded by a count, not terminated by a null character). They do not 
check for the overflow of any receiving memory area. 

Memccpy copies characters from memory area s2 into si, stopping after the first 
occurrence of character c has been copied, or after n characters have been 
copied, whichever comes first. It returns a pointer to the character after the copy 
of c in si, or a NULL pointer if c was not found in the first n characters of s2. 

Memchr returns a pointer to the first occurrence of character c in the first n char- 
acters of memory area s, or a NULL pointer if c does not occur. 

Memcmp compares its arguments, looking at the first n characters only, and 
returns an integer less than, equal to, or greater than 0, according as si is lexico- 
graphically less than, equal to, or greater than s2. 

Memcpy copies n characters from memory area s2 to si. It returns si. 

Memset sets the first n characters in memory area s to the value of character c. 
It returns s. 

For user convenience, all these functions are declared in the optional 
<memory.h> header file. 
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CAVEATS 

Memcmp is implemented by using the most natural character comparison on the 
machine. Thus the sign of the value returned when one of the characters has its 
high order bit set is not the same in all implementations and should not be 
relied upon. 

Character movement is performed differently in different implementations. Thus 
overlapping moves may yield surprises. 
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NAME 

mktemp — make a unique file name 
SYNOPSIS 

char *mktemp (template) 
char *template; 

DESCRIPTION 

mktemp replaces the contents of the string pointed to by template by a unique 
file name, and returns the address of template. The string in template should 
look like a file name with six trailing Xs; mktemp will replace the Xs with a letter 
and the current process ID. The letter will be chosen so that the resulting name 
does not duplicate an existing file. 

SEE ALSO 

getpid(2), tmpfile(3S), tmpnam(3S). 

DIAGNOSTIC 

mktemp will assign to template the NULL string if it cannot create a unique 
name. 

CAVEAT 

If called more than 17,576 time in a single process, this function will start recy- 
cling previously used names. 
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NAME 

monitor — prepare execution profile 
SYNOPSIS 

#include <mon.h> 

void monitor (lowpc, highpc, buffer, bufsize, nfunc) 
int (*lowpc)( ), (*highpc)( ); 

WORD ^buffer; 
int bufsize, nfunc; 

DESCRIPTION 

An executable program created by cc — p automatically includes calls for monitor 
with default parameters; monitor need not be called explicitly except to gain fine 
control over profiling. 

monitor is an interface to profil(2). Lowpc and highpc are the addresses of two 
functions; buffer is the address of a (user supplied) array of bufsize WORDs 
(defined in the <mon.h> header file), monitor arranges to record a histogram of 
periodically sampled values of the program counter, and of counts of calls of 
certain functions, in the buffer. The lowest address sampled is that of lowpc and 
the highest is just below highpc. Lowpc may not equal 0 for this use of monitor. 
At most nfunc call counts can be kept; only calls of functions compiled with the 
profiling option — p of cc(l) are recorded. 

For the results to be significant, especially where there are small, heavily used 
routines, it is suggested that the buffer be no more than a few times smaller than 
the range of locations sampled. 

To profile the entire program, it is sufficient to use 
extern etext; 

monitor ((int (*)())2, &etext, buf, bufsize, nfunc); 

Etext lies just above all the program text; see end( 3C). 

To stop execution monitoring and write the results, use 
monitor ((int (*)())0, 0, 0, 0, 0); 

Pro/(l) can then be used to examine the results. 

The name of the file written by monitor is controlled by the environment vari- 
able PROFDIR. If PROFDIR does not exist, "mon.out" is created in the current 
directory. If PROFDIR exists but has no value, monitor does not do any profiling 
and creates no output file. Otherwise, the value of PROFDIR is used as the name 
of the directory in which to create the output file. If PROFDIR is dirname, then 
the file written is " dirname / pid . mon.out" where pid is the program's process id. 
(When monitor is called automatically by compiling via cc — p, the file created is 
"dirname /pid.progname" where progname is the name of the program.) 

FILES 

mon.out 
SEE ALSO 

cc(l), prof(l), profil(2), end(3C). 
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BUGS 

The "dirname/pid.m on.out" form does not work; the "dirname/pid.progname" 
form (automatically called via cc — p) does work. 
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NAME 

nlist — get entries from name list 
SYNOPSIS 

#include <nlist.h> 

int nlist (filename, nl) 
char *filename; 
struct nlist *nl; 

DESCRIPTION 

nlist examines the name list in the executable file whose name is pointed to by 
filename, and selectively extracts a list of values and puts them in the array of 
nlist structures pointed to by nl. The name list nl consists of an array of struc- 
tures containing names of variables, types and values. The list is terminated 
with a null name; that is, a null string is in the name position of the structure. 
Each variable name is looked up in the name list of the file. If the name is 
found, the type and value of the name are inserted in the next two fields. The 
type field will be set to 0 unless the file was compiled with the — g option. If the 
name is not found, both entries are set to 0. See a.out( 4) for a discussion of the 
symbol table structure. 

This function is useful for examining the system name list kept in the file /unix. 
In this way programs can obtain system addresses that are up to date. 

NOTES 

The <nlist.h> header file is automatically included by <a.out.h> for compata- 
bility. However, if the only information needed from <a.out.h> is for use of 
nlist, then including <a.out.h> is discouraged. If <a.out.h> is included, the 
line "#undef n_name" may need to follow it. 

SEE ALSO 

a.out(4). 

DIAGNOSTICS 

All value entries are set to 0 if the file cannot be read or if it does not contain a 
valid name list. 

nlist returns —1 upon error; otherwise it returns 0. 



317 




PERROR(3C) 



(C Programming Language Utilities) 



PERROR(3C) 



NAME 

perror, errno, sys_errlist, sys_nerr — system error messages 

SYNOPSIS 

void perror (s) 
char *s; 

extern int errno; 
extern char *sys_errlist[ ]; 
extern int sys nerr; 

DESCRIPTION 

perror produces a message on the standard error output, describing the last error 
encountered during a call to a system or library function. The argument string s 
is printed first, then a colon and a blank, then the message and a new-line. 
(However, if s="" the colon is not printed.) To be of most use, the argument 
string should include the name of the program that incurred the error. The error 
number is taken from the external variable errno, which is set when errors occur 
but not cleared when non-erroneous calls are made. 

To simplify variant formatting of messages, the array of message strings 
sys_errlist is provided; errno can be used as an index into this table to get the 
message string without the new-line. Sysjierr is the number of messages in the 
table; it should be checked because new error codes may be added to the system 
before they are added to the table. 

SEE ALSO 

intro(2). 
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NAME 

popen, pclose — initiate pipe to/from a process 
SYNOPSIS 

#include <stdio.h> 

FILE *popen (command, type) 
char ^command, *type; 

int pclose (stream) 

FILE ^stream; 

DESCRIPTION 

popen creates a pipe between the calling program and the command to be exe- 
cuted. The arguments to popen are pointers to null-terminated strings. Com- 
mand consists of a shell command line. Type is an I/O mode, either r for 
reading or w for writing. The value returned is a stream pointer such that one 
can write to the standard input of the command, if the I/O mode is w, by 
writing to the file stream; and one can read from the standard output of the com- 
mand, if the I/O mode is r, by reading from the file stream. 

A stream opened by popen should be closed by pclose, which waits for the asso- 
ciated process to terminate and returns the exit status of the command. 

Because open files are shared, a type r command may be used as an input filter 
and a type w as an output filter, 

EXAMPLE 

A typical call may be: 

char *cmd — "Is *.c"; 

FILE *ptr; 

if ((ptr = popen(cmd, V)) != NULL) 
while (fgets(buf, n, ptr) !— NULL) 

(void) printf("%s ",buf); 

This will print in stdout [see stdio (3S)] all the file names in the current directory 
that have a ",c" suffix. 

SEE ALSO 

pipe(2), wait(2), fclose(3S), fopen(3S), stdio(3S), system(3S). 

DIAGNOSTICS 

popen returns a NULL pointer if files or processes cannot be created. 

Pclose returns —1 if stream is not associated with a "popen ed" command. 
WARNING 

If the original and "popen ed" processes concurrently read or write a common 
file, neither should use buffered I/O, because the buffering gets all mixed up. 
Problems with an output filter may be forestalled by careful buffer flushing, e.g. 
with fflush [see f close (3S)]. 
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NAME 

printf, fprintf, sprintf — print formatted output 
SYNOPSIS 

#include <stdio.h> 

int printf (format , arg ... ) 

char *format; 

int fprintf (stream, format , arg ... ) 

FILE ^stream; 
char ^format; 

int sprintf (s, format [ , arg ] ... ) 

char *s, ^format; 

DESCRIPTION 

printf places output on the standard output stream stdout. Fprintf places output 
on the named output stream. Sprintf places "output," followed by the null char- 
acter (\0), in consecutive bytes starting at *s; it is the user's responsibility to 
ensure that enough storage is available. Each function returns the number of 
characters transmitted (not including the \0 in the case of sprintf), or a negative 
value if an output error was encountered. 

Each of these functions converts, formats, and prints its args under control of the 
format. The format is a character string that contains two types of objects: plain 
characters, which are simply copied to the output stream, and conversion 
specifications, each of which results in fetching of zero or more args. The results 
are undefined if there are insufficient args for the format. If the format is 
exhausted while args remain, the excess args are simply ignored. 

Each conversion specification is introduced by the character %. After the °/o, the 
following appear in sequence: 

Zero or more flags , which modify the meaning of the conversion 
specification. 

An optional decimal digit string specifying a minimum field width . If the 
converted value has fewer characters than the field width, it will be 
padded on the left (or right, if the left-adjustment flag described 
below, has been given) to the field width. The padding is with blanks 
unless the field width digit string starts with a zero, in which case the 
padding is with zeros. 

A precision that gives the minimum number of digits to appear for the d, 
i, o, u, x, or X conversions, the number of digits to appear after the 
decimal point for the e, E, and f conversions, the maximum number of 
significant digits for the g and G conversion, or the maximum number of 
characters to be printed from a string in s conversion. The precision 
takes the form of a period (.) followed by a decimal digit string; a null 
digit string is treated as zero. Padding specified by the precision over- 
rides the padding specified by the field width. 

An optional 1 (ell) specifying that a following d, i, o, u, x, or X conver- 
sion character applies to a long integer arg An 1 before any other 
conversion character is ignored. 
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A character that indicates the type of conversion to be applied. 

A field width or precision or both may be indicated by an asterisk (*) instead of 
a digit string. In this case, an integer arg supplies the field width or precision. 
The arg that is actually converted is not fetched until the conversion letter is 
seen, so the args specifying field width or precision must appear before the arg 
(if any) to be converted. A negative field width argument is taken as a ' flag 
followed by a positive field width. If the precision argument is negative, it will 
be changed to zero. 

The flag characters and their meanings are: 

— The result of the conversion will be left- justified within the field. 

+ The result of a signed conversion will always begin with a sign (+ or 

-)• 

blank If the first character of a signed conversion is not a sign, a blank will 
be prefixed to the result. This implies that if the blank and + flags 
both appear, the blank flag will be ignored. 

# This flag specifies that the value is to be converted to an "alternate 

form." For c, d, i, s, and u conversions, the flag has no effect. For o 
conversion, it increases the precision to force the first digit of the 
result to be a zero. For x or X conversion, a non-zero result will have 
Ox or OX prefixed to it. For e, E, f, g, and G conversions, the result 
will always contain a decimal point, even if no digits follow the point 
(normally, a decimal point appears in the result of these conversions 
only if a digit follows it). For g and G conversions, trailing zeroes 
will not be removed from the result (which they normally are). 

The conversion characters and their meanings are: 

d, i,o,u,x,X The integer arg is converted to signed decimal (d or i), unsigned 

octal, (o), decimal (u), or hexadecimal notation (x or X), respectively; 
the letters abcdef are used for x conversion and the letters ABCDEF 
for X conversion. The precision specifies the minimum number of 
digits to appear; if the value being converted can be represented in 
fewer digits, it will be expanded with leading zeroes. The default 
precision is 1. The result of converting a zero value with a precision 
of zero is a null string. 

f The float or double arg is converted to decimal notation in the style 

"[— Jddd.ddd," where the number of digits after the decimal point is 
equal to the precision specification. If the precision is missing, six 
digits are output; if the precision is explicitly 0, no decimal point 
appears. 

e, E The float or double arg is converted in the style "[— ]d.ddde±dd," 

where there is one digit before the decimal point and the number of 
digits after it is equal to the precision; when the precision is missing, 
six digits are produced; if the precision is zero, no decimal point 
appears. The E format code will produce a number with E instead of 
e introducing the exponent. The exponent always contains at least 
two digits. 
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In printing floating point types (float and double), if the exponent is 0x7FF and 
the mantissa is not equal to zero, then the output is 

[-]NaNOxdddddddd 

where Oxdddddddd is the hexadecimal representation of the leftmost 32 bits of 
the mantissa. If the mantissa is zero, the output is 

[±]inf. 

In no case does a non-existent or small field width cause truncation of a field; if 
the result of a conversion is wider than the field width, the field is simply 
expanded to contain the conversion result. Characters generated by printf and 
fprintf are printed as if putc( 3S) had been called. 

EXAMPLES 

To print a date and time in the form "Sunday, July 3, 10:02," where weekday 
and month are pointers to null-terminated strings: 

printf("%s, %s %i, %d:%.2d", weekday, month, day, hour, min); 

To print t to 5 decimal places: 

printf ("pi = %.5f", 4 * atan(l.O)); 

SEE ALSO 

ecvt(3C), putc(3S), scanf(3S), stdio(3S). 
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The float or double arg is printed in style f or e (or in style E in the 
case of a G format code), with the precision specifying the number of 
significant digits. The style used depends on the value converted: 
style e will be used only if the exponent resulting from the conver- 
sion is less than —4 or greater than the precision. Trailing zeroes are 
removed from the result; a decimal point appears only if it is fol- 
lowed by a digit. 

The character arg is printed. 

The arg is taken to be a string (character pointer) and characters from 
the string are printed until a null character (\0) is encountered or the 
number of characters indicated by the precision specification is 
reached. If the precision is missing, it is taken to be infinite, so all 
characters up to the first null character are printed. A NULL value for 
arg will yield undefined results. 

Print a %; no argument is converted. 
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NAME 

putc, putchar, fputc, putw — put character or word on a stream 
SYNOPSIS 

#include <stdio.h> 

int putc (c, stream) 
int c; 

FILE *stream; 

int putchar (c) 
int c; 

int fputc (c, stream) 
int c; 

FILE *stream; 

int putw (w, stream) 
int w; 

FILE *stream; 

DESCRIPTION 

putc writes the character c onto the output stream (at the position where the file 
pointer, if defined, is pointing). putchar(c) is defined as putc(c, stdout). putc and 
putchar are macros. 

Fputc behaves like putc, but is a function rather than a macro. Fputc runs more 
slowly than putc, but it takes less space per invocation and its name can be 
passed as an argument to a function. 

Putw writes the word (i.e. integer) w to the output stream (at the position at 
which the file pointer, if defined, is pointing). The size of a word is the size of 
an integer and varies from machine to machine. Putw neither assumes nor 
causes special alignment in the file. 

SEE ALSO 

fclose(3S), ferror(3S), fopen(3S), fread(3S), printf(3S), puts(3S), setbuf(3S), 
stdio(3S). 

DIAGNOSTICS 

On success, these functions (with the exception of putw) each return the value 
they have written. [Putw returns ferror (stream)]. On failure, they return the con- 
stant EOF. This will occur if the file stream is not open for writing or if the 
output file cannot grow. Because EOF is a valid integer, ferror( 3S) should be 
used to detect putw errors. 

CAVEATS 

Because it is implemented as a macro, putc evaluates a stream argument more 
than once. In particular, putc(c, *f++); doesn't work sensibly. Fputc should be 
used instead. 

Because of possible differences in word length and byte ordering, files written 
using putw are machine-dependent, and may not be read using getw on a 
different processor. 
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NAME 

putenv — change or add value to environment 

SYNOPSIS 

int putenv (string) 
char *string; 

DESCRIPTION 

String points to a string of the form "name=value." putenv makes the value of 
the environment variable name equal to value by altering an existing variable or 
creating a new one. In either case, the string pointed to by string becomes part 
of the environment, so altering the string will change the environment. The 
space used by string is no longer used once a new string-defining name is passed 
to putenv. 

SEE ALSO 

exec(2), getenv(3C), malloc(3C), environ(5). 

DIAGNOSTICS 

putenv returns non-zero if it was unable to obtain enough space via malloc for 
an expanded environment, otherwise zero. 

WARNINGS 

putenv manipulates the environment pointed to by environ, and can be used in 
conjunction with getenv. However, envp (the third argument to main) is not 
changed. 

This routine uses malloc( 3C) to enlarge the environment. 

After putenv is called, environmental variables are not in alphabetical order. 

A potential error is to call putenv with an automatic variable as the argument, 
then exit the calling function while string is still part of the environment. 
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NAME 

putpwent — write password file entry 
SYNOPSIS 

#include <pwd.h> 

int putpwent (p, f) 
struct passwd *p; 

FILE *f; 

DESCRIPTION 

putpwent is the inverse of getpwent( 3C). Given a pointer to a passwd structure 
created by getpwent (or getpwuid or getpwnam), putpwent writes a line on the 
stream /, which matches the format of /etc/passwd. 

SEE ALSO 

getpwent(3C). 

DIAGNOSTICS 

putpwent returns non-zero if an error was detected during its operation, other- 
wise zero. 

WARNING 

The above routine uses <stdio.h>, which causes it to increase the size of pro- 
grams, not otherwise using standard I/O, more than might be expected. 
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NAME 

puts, fputs — put a string on a stream 
SYNOPSIS 

#include <stdio.h> 

int puts (s) 
char *s; 

int fputs (s, stream) 
char *s; 

FILE *stream; 

DESCRIPTION 

puts writes the null-terminated string pointed to by s followed by a new-line 
character, to the standard output stream stdout. 

Fputs writes the null-terminated string pointed to by s to the named output 
stream. 

Neither function writes the terminating null character. 

SEE ALSO 

ferror(3S), fopen(3S), fread(3S), printf(3S), putc(3S), stdio(3S). 

DIAGNOSTICS 

Both routines return EOF on error. This will happen if the routines try to write 
on a file that has not been opened for writing. 

NOTES 

puts appends a new-line character while fputs does not. 
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NAME 

qsort — quicker sort 
SYNOPSIS 

void qsort ((char *) base, nel, sizeof (*base), compar) 
unsigned nel; 
int (*compar)( ); 

DESCRIPTION 

qsort is an implementation of the quicker-sort algorithm. It sorts a table of data 
in place. 

Base points to the element at the base of the table. Nel is the number of ele- 
ments in the table. Compar is the name of the comparison function, which is 
called with two arguments that point to the elements being compared. As the 
function must return an integer less than, equal to, or greater than zero, so must 
the first argument to be considered be less than, equal to, or greater than the 
second. 

NOTES 

The pointer to the base of the table should be of type pointer-to-element, and 
cast to type pointer- to-character. 

The comparison function need not compare every byte, so arbitrary data may be 
contained in the elements in addition to the values being compared. 

The order in the output of two items which compare as equal is unpredictable. 

SEE ALSO 

bsearch(3C), lsearch(3C), string(3C). 
sort(l) in the User's Reference Manual. 
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NAME 

rand, srand — simple random-number generator 

SYNOPSIS 

int rand ( ) 

void srand (seed) 
unsigned seed; 

DESCRIPTION 

rand uses a multiplicative congruential random-number generator with period 
2 31 that returns successive pseudo-random numbers in the range from 0 to 
2 15 — 1. 

Srand can be called at any time to reset the random-number generator to a 
random starting point. The generator is initially seeded with a value of 1 . 

NOTES 

The spectral properties of rand are limited. Drand48( 3C) provides a much better, 
though more elaborate, random-number generator. 

SEE ALSO 

drand48(3C). 
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NAME 

scanf, fscanf, sscanf — convert formatted input 
SYNOPSIS 

#include <stdio.h> 

int scanf (format [ , pointer ] ... ) 

char * format; 

int fscanf (stream, format [ , pointer ] ... ) 

FILE *stream; 
char * format; 

int sscanf (s, format [ , pointer ] ... ) 

char *s, * format; 

DESCRIPTION 

scanf reads from the standard input stream stdin. Fscanf reads from the named 
input stream. Sscanf reads from the character string s. Each function reads char- 
acters, interprets them according to a format, and stores the results in its argu- 
ments. Each expects, as arguments, a control string format described below, and 
a set of pointer arguments indicating where the converted input should be 
stored. The results are undefined in there are insufficient args for the format. If 
the format is exhausted while args remain, the excess args are simply ignored. 

The control string usually contains conversion specifications, which are used to 
direct interpretation of input sequences. The control string may contain: 

1. White-space characters (blanks, tabs, new-lines, or form-feeds) which, except 
in two cases described below, cause input to be read up to the next non- 
white-space character. 

2. An ordinary character (not %), which must match the next character of the 
input stream. 

3. Conversion specifications, consisting of the character %, an optional assign- 
ment suppressing character *, an optional numerical maximum field width, an 
optional 1 (ell) or h indicating the size of the receiving variable, and a 
conversion code. 

A conversion specification directs the conversion of the next input field; the 
result is placed in the variable pointed to by the corresponding argument, unless 
assignment suppression was indicated by *. The suppression of assignment pro- 
vides a way of describing an input field which is to be skipped. An input field is 
defined as a string of non-space characters; it extends to the next inappropriate 
character or until the field width, if specified, is exhausted. For all descriptors 
except "[" and "c", white space leading an input field is ignored. 

The conversion code indicates the interpretation of the input field; the 
corresponding pointer argument must usually be of a restricted type. For a 
suppressed field, no pointer argument is given. The following conversion codes 
are legal: 

% a single % is expected in the input at this point; no assignment is done. 

d a decimal integer is expected; the corresponding argument should be an 

integer pointer. 
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an unsigned decimal integer is expected; the corresponding argument 
should be an unsigned integer pointer. 

an octal integer is expected; the corresponding argument should be an 
integer pointer. 

a hexadecimal integer is expected; the corresponding argument should 
be an integer pointer. 

an integer is expected; the corresponding argument should be an integer 
pointer. It will store the value of the next input item interpreted 
according to C conventions: a leading "0" implies octal; a leading "Ox" 
implies hexadecimal; otherwise, decimal. 

stores in an integer argument the total number of characters (including 
white space) that have been scanned so far since the function call. No 
input is consumed. 

a floating point number is expected; the next field is converted accord- 
ingly and stored through the corresponding argument, which should be 
a pointer to a float. The input format for floating point numbers is an 
optionally signed string of digits, possibly containing a decimal point, 
followed by an optional exponent field consisting of an E or an e, fol- 
lowed by an optional +, — , or space, followed by an integer. 

a character string is expected; the corresponding argument should be a 
character pointer pointing to an array of characters large enough to 
accept the string and a terminating \0, which will be added automati- 
cally. The input field is terminated by a white-space character. 

a character is expected; the corresponding argument should be a char- 
acter pointer. The normal skip over white space is suppressed in this 
case; to read the next non-space character, use %ls. If a field width is 
given, the corresponding argument should refer to a character array; the 
indicated number of characters is read. 

indicates string data and the normal skip over leading white space is 
suppressed. The left bracket is followed by a set of characters, which 
we will call the scanset, and a right bracket; the input field is the max- 
imal sequence of input characters consisting entirely of characters in the 
scanset. The circumflex ( A ), when it appears as the first character in the 
scanset, serves as a complement operator and redefines the scanset as 
the set of all characters not contained in the remainder of the scanset 
string. There are some conventions used in the construction of the 
scanset. A range of characters may be represented by the construct 
first— last, thus [0123456789] may be expressed [0—9]. Using this con- 
vention, first must be lexically less than or equal to last, or else the dash 
will stand for itself. The dash will also stand for itself whenever it is the 
first or the last character in the scanset. To include the right square 
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bracket as an element of the scanset, it must appear as the first character 
(possibly preceded by a circumflex) of the scanset, and in this case it will 
not be syntactically interpreted as the closing bracket. The 
corresponding argument must point to a character array large enough to 
hold the data field and the terminating \0, which will be added automat- 
ically. At least one character must match for this conversion to be con- 
sidered successful. 

The conversion characters d, u, o, x and i may be preceded by 1 or h to indicate 
that a pointer to long or to short rather than to int is in the argument list. 
Similarly, the conversion characters e, f, and g may be preceded by 1 to indicate 
that a pointer to double rather than to float is in the argument list. The 1 or h 
modifier is ignored for other conversion characters. 

scanf conversion terminates at EOF, at the end of the control string, or when an 
input character conflicts with the control string. In the latter case, the offending 
character is left unread in the input stream. 

scanf returns the number of successfully matched and assigned input items; this 
number can be zero in the event of an early conflict between an input character 
and the control string. If the input ends before the first conflict or conversion, 
EOF is returned. 

EXAMPLES 

The call: 

int n ; float x; char name[50]; 
n = scanf ("%d%f%s", &i, &x, name); 

with the input line: 

25 54.32E— 1 thompson 

will assign to n the value 3, to i the value 25, to x the value 5.432, and name will 
contain thompson\0 . Or: 

int i, j; float x; char name[50]; 

(void) scanf ("%i%2d%f%*d %[0 — 9] ”, &j, &i, &x, name); 
with input: 

Oil 56789 0123 56a72 

will assign 9 to j, 56 to i, 789.0 to x, skip 0123, and place the string 56\0 in name. 
The next call to getchar [see getc( 3S)] will return a. Or: 

int i, j, s, e; char name[50]; 

(void) scanf ("%i %i %n%s%n", &i, &j, &s, name, &e); 
with input: 

0x11 Oxy johnson 

will assign 17 to i, 0 to /, 6 to s, will place the string xy\0 in name, and will 
assign 8 to e. Thus, the length of name is e - s — 2 . The next call to getchar 
[see getc( 3S)] will return a blank. 

SEE ALSO 

getc(3S), printf(3S), stdio(3S), strtod(3C), strtol(3C). 
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DIAGNOSTICS 

These functions return EOF on end of input and a short count for missing or 
illegal data items. 

CAVEATS 

Trailing white space (including a new-line) is left unread unless matched in the 
control string. 
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NAME 

setbuf, setvbuf — assign buffering to a stream 
SYNOPSIS 

#include <stdio.h> 

void setbuf (stream, buf) 

FILE *stream; 
char *buf; 

int setvbuf (stream, buf, type, size) 

FILE *stream; 
char *buf; 
int type, size; 

DESCRIPTION 

setbuf may be used after a stream has been opened but before it is read or 
written. It causes the array pointed to by buf to be used instead of an automati- 
cally allocated buffer. If buf is the NULL pointer input/output will be completely 
unbuffered. 

A constant BUFSIZ, defined in the <stdio.h> header file, tells how big an array 
is needed: 

char buf[BUFSIZ]; 

Setvbuf may be used after a stream has been opened but before it is read or 
written. Type determines how stream will be buffered. Legal values for type 
(defined in stdio.h) are: 

IOFBF causes input/output to be fully buffered. 

IOLBF causes output to be line buffered; the buffer will be flushed when 

a newline is written, the buffer is full, or input is requested. 

_IONBF causes input/output to be completely unbuffered. 

If buf is not the NULL pointer, the array it points to will be used for buffering, 
instead of an automatically allocated buffer. Size specifies the size of the buffer 
to be used. The constant BUFSIZ in < stdio.h > is suggested as a good buffer 
size. If input/output is unbuffered, buf and size are ignored. 

By default, output to a terminal is line buffered and all other input/output is 
fully buffered. 

SEE ALSO 

fopen(3S), getc(3S), malloc(3C), putc(3S), stdio(3S). 

DIAGNOSTICS 

If an illegal value for type or size is provided, setvbuf returns a non-zero value. 
Otherwise, the value returned will be zero. 

NOTES 

A common source of error is allocating buffer space as an "automatic" variable 
in a code block, and then failing to close the stream in the same block. 
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NAME 

setjmp, longjmp — non-local goto 
SYNOPSIS 

#include <setjmp.h> 

int setjmp (env) 
jmp buf env; 

void longjmp (env, val) 
jmp buf env; 
int val; 

DESCRIPTION 

These functions are useful for dealing with errors and interrupts encountered in 
a low-level subroutine of a program. 

setjmp saves its stack environment in env (whose type, jmp_buf, is defined in the 
<setjmp.h> header file) for later use by longjmp. It returns the value 0. 

Longjmp restores the environment saved by the last call of setjmp with the 
corresponding env argument. After longjmp is completed, program execution 
continues as if the corresponding call of setjmp (which must not itself have 
returned in the interim) had just returned the value val. Longjmp cannot cause 
setjmp to return the value 0. If longjmp is invoked with a second argument of 0, 
setjmp will return 1. At the time of the second return from setjmp , all accessible 
data have values as of the time longjmp is called. However, global variables will 
have the expected values, i.e. those as of the time of the longjmp (see example). 

EXAMPLE 

#include <setjmp.h> 

jmpjbuf env; 
int i = 0; 
main () 

void exitQ; 
if(setjmp(env) != 0) { 

(void) printf('Value of i on 2nd return from setjmp: %d\n", i); 
exit(0); 

} 

(void) printf("valuei of i on 1st return from setjmp: %d\n", i); 

i = 1; 
g(); 

/*NOTREACHED* / 



so 

{ 

longjmp(env, 1); 
/*NOTREACHED» / 
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If the a. out resulting from this C language code is run, the 
output will be: 

value of i on 1st return from setjmp:0 
value of i on 2nd return from setjmp:l 

SEE ALSO 

signal(2). 

WARNING 

If longjmp is called even though env was never primed by a call to setjmp, or 
when the last such call was in a function which has since returned, absolute 
chaos is guaranteed. 

BUGS 

The values of the registers on the second return from setjmp are the register 
values at the time of the first call to setjmp , not those at the time of the longjmp. 
This means that variables in a given function may behave differently in the pres- 
ence of setjmp, depending on whether they are register or stack variables. 
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NAME 

sleep — suspend execution for interval 
SYNOPSIS 

unsigned sleep (seconds) 
unsigned seconds; 

DESCRIPTION 

The current process is suspended from execution for the number of seconds 
specified by the argument. The actual suspension time may be less than that 
requested for two reasons: (1) Because scheduled wakeups occur at fixed 1- 
second intervals, (on the second, according to an internal clock) and (2) because 
any caught signal will terminate the sleep following execution of that signal's 
catching routine. Also, the suspension time may be longer than requested by an 
arbitrary amount due to the scheduling of other activity in the system. The 
value returned by sleep will be the "unslept" amount (the requested time minus 
the time actually slept) in case the caller had an alarm set to go off earlier than 
the end of the requested sleep time, or premature arousal due to another caught 
signal. 

The routine is implemented by setting an alarm signal and pausing until it (or 
some other signal) occurs. The previous state of the alarm signal is saved and 
restored. The calling program may have set up an alarm signal before calling 
sleep. If the sleep time exceeds the time till such alarm signal, the process sleeps 
only until the alarm signal would have occurred. The caller's alarm catch rou- 
tine is executed just before the sleep routine returns. But if the sleep time is less 
than the time till such alarm, the prior alarm time is reset to go off at the same 
time it would have without the intervening sleep. 

SEE ALSO 

alarm(2), pause(2), signal(2). 
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NAME 

ssignal, gsignal — software signals 
SYNOPSIS 

#include <signal.h> 

int (*ssignal (sig, action))( ) 
int sig, (*action)( ); 

int gsignal (sig) 
int sig; 

DESCRIPTION 

ssignal and gsignal implement a software facility similar to signal^ 2). This facility 
is used by the Standard C Library to enable users to indicate the disposition of 
error conditions, and is also made available to users for their own purposes. 

Software signals made available to users are associated with integers in the 
inclusive range 1 through 16. A call to ssignal associates a procedure, action, 
with the software signal sig; the software signal, sig, is raised by a call to gsignal. 
Raising a software signal causes the action established for that signal to be taken. 

The first argument to s signal is a number identifying the type of signal for which 
an action is to be established. The second argument defines the action; it is 
either the name of a (user-defined) action function or one of the manifest con- 
stants SIGDFL (default) or SIGJGN (ignore), ssignal returns the action previ- 
ously established for that signal type; if no action has been established or the 
signal number is illegal, ssignal returns SIG DFL. 

Gsignal raises the signal identified by its argument, sig: 

If an action function has been established for sig, then that action is reset 
to SIG_DFL and the action function is entered with argument sig. Gsignal 
returns the value returned to it by the action function. 

If the action for sig is SIGJGN, gsignal returns the value 1 and takes no 
other action. 

If the action for sig is SIG DFL, gsignal returns the value 0 and takes no 
other action. 

If sig has an illegal value or no action was ever specified for sig, gsignal 
returns the value 0 and takes no other action. 



SEE ALSO 

signal(2), sigset(2). 

NOTES 

There are some additional signals with numbers outside the range 1 through 16 
which are used by the Standard C Library to indicate error conditions. Thus, 
some signal numbers outside the range 1 through 16 are legal, although their 
use may interfere with the operation of the Standard C Library. 
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NAME 

stdio — standard buffered input/output package 
SYNOPSIS 

#include <stdio.h> 

FILE *stdin, *stdout, *stderr; 

DESCRIPTION 

The functions described in the entries of sub-class 3S of this manual constitute 
an efficient, user-level I/O buffering scheme. The in-line macros getc( 3S) and 
putc( 3S) handle characters quickly. The macros getchar and putchar, and the 
higher-level routines fgetc, fgets, fprintf, fputc, fputs, fread, fscanf, fwrite, gets , 
getw, printf, puts, putzv, and scanf all use or act as if they use getc and putc; they 
can be freely intermixed. 

A file with associated buffering is called a stream and is declared to be a pointer 
to a defined type FILE. Fopen( 3S) creates certain descriptive data for a stream 
and returns a pointer to designate the stream in all further transactions. Nor- 
mally, there are three open streams with constant pointers declared in the 
<stdio.h> header file and associated with the standard open files: 

stdin standard input file 

stdout standard output file 

stderr standard error file 

A constant NULL (0) designates a nonexistent pointer. 

An integer-constant EOF (—1) is returned upon end-of-file or error by most 
integer functions that deal with streams (see the individual descriptions for 
details). 

An integer constant BUFSIZ specifies the size of the buffers used by the partic- 
ular implementation. 

Any program that uses this package must include the header file of pertinent 
macro definitions, as follows: 

#include <stdio.h> 

The functions and constants mentioned in the entries of sub-class 3S of this 
manual are declared in that header file and need no further declaration. The 
constants and the following "functions" are implemented as macros (redeclara- 
tion of these names is perilous): getc, getchar, putc, putchar, ferror, feof, clearerr, 
and fileno. 

Output streams, with the exception of the standard error stream stderr, are by 
default buffered if the output refers to a file and line-buffered if the output refers 
to a terminal. The standard error output stream stderr is by default unbuffered, 
but use of freopen [see fopen( 3S)] will cause it to become buffered or line- 
buffered. When an output stream is unbuffered, information is queued for 
writing on the destination file or terminal as soon as written; when it is buffered, 
many characters are saved up and written as a block. When it is 
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line-buffered, each line of output is queued for writing on the destination ter- 
minal as soon as the line is completed (that is, as soon as a new-line character is 
written or terminal input is requested). Setbuf( 3S) or setvbufQ in setbuf( 3S) may 
be used to change the stream's buffering strategy. 

SEE ALSO 

open(2), close(2), lseek(2), pipe(2), read(2), write(2), ctermid(3S), cuserid(3S), 
fclose(3S), ferror(3S), fopen(3S), fread(3S), fseek(3S), getc(3S), gets(3S), 
popen(3S), printf(3S), putc(3S), puts(3S), scanf(3S), setbuf(3S), system(3S), 
tmpfile(3S), tmpnam(3S), ungetc(3S). 

DIAGNOSTICS 

Invalid stream pointers will usually cause grave disorder, possibly including pro- 
gram termination. Individual function descriptions describe the possible error 
conditions. 
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NAME 

stdipc: ftok — standard interprocess communication package 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/ipc.h> 

key t ftokfpath, id) 
char *path; 
char id; 

DESCRIPTION 

All interprocess communication facilities require the user to supply a key to be 
used by the msgget( 2), semget( 2), and shmget(2) system calls to obtain interpro- 
cess communication identifiers. One suggested method for forming a key is to 
use the ftok subroutine described below. Another way to compose keys is to 
include the project ID in the most significant byte and to use the remaining por- 
tion as a sequence number. There are many other ways to form keys, but it is 
necessary for each system to define standards for forming them. If some stan- 
dard is not adhered to, it will be possible for unrelated processes to unintention- 
ally interfere with each other's operation. Therefore, it is strongly suggested that 
the most significant byte of a key in some sense refer to a project so that keys 
do not conflict across a given system. 

Ftok returns a key based on path and id that is usable in subsequent msgget, 
semget, and shmget system calls. Path must be the path name of an existing file 
that is accessible to the process. Id is a character which uniquely identifies a 
project. Note that ftok will return the same key for linked files when called with 
the same id and that it will return different keys when called with the same file 
name but different ids. 

SEE ALSO 

intro(2), msgget(2), semget(2), shmget(2). 

DIAGNOSTICS 

Ftok returns (key_t) — 1 if path does not exist or if it is not accessible to the pro- 
cess. 

WARNING 

If the file whose path is passed to ftok is removed when keys still refer to the 
file, future calls to ftok with the same path and id will return an error. If the 
same file is recreated, then ftok is likely to return a different key than it did the 
original time it was called. 
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NAME 

string: strcat, strdup, strncat, strcmp, strncmp, strcpy, strncpy, strlen, strchr, 
strrchr, strpbrk, strspn, strcspn, strtok — string operations 

SYNOPSIS 

#include <string.h> 

#include <sys/types.h> 

char *strcat (si, s2) 
char *sl, *s2; 

char *strdup (si) 
char *sl; 

char *strncat (si, s2, n) 
char *sl, *s2; 
sizet n; 

int strcmp (si, s2) 
char *sl, *s2; 

int strncmp (si, s2, n) 
char *sl, *s2; 
size t n; 

char *strcpy (si, s2) 
char *sl, *s2; 

char *strncpy (si, s2, n) 
char *sl, *s2; 
size t n; 

int strlen (s) 
char *s; 

char *strchr (s, c) 
char *s; 
int c; 

char *strrchr (s, c) 
char *s; 
int c; 

char * strpbrk (si, s2) 
char *sl, *s2; 

int strspn (si, s2) 
char *sl, *s2; 

int strcspn (si, s2) 
char *sl, *s2; 

char *strtok (si, s2) 
char *sl, *s2; 

DESCRIPTION 

The arguments si, s2 and s point to strings (arrays of characters terminated by a 
null character). The functions strcat, strncat, strcpy, and strncpy all alter si. 
These functions do not check for overflow of the array pointed to by si. 
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Strcat appends a copy of string s2 to the end of string si. 

Strdup returns a pointer to a new string which is a duplicate of the string 
pointed to by si. The space for the new string is obtained using malloc( 3C). If 
the new string can not be created, null is returned. 

Strncat appends at most n characters. Each returns a pointer to the null- 
terminated result. 

Strcmp compares its arguments and returns an integer less than, equal to, or 
greater than 0, according as si is lexicographically less than, equal to, or greater 
than s2. Strncmp makes the same comparison but looks at at most n characters. 

Strcpy copies string s2 to si, stopping after the null character has been copied. 
Strncpy copies exactly n characters, truncating s2 or adding null characters to si 
if necessary. The result will not be null-terminated if the length of s2 is n or 
more. Each function returns si. 

Strlen returns the number of characters in s, not including the terminating null 
character. 

Strchr ( strrchr ) returns a pointer to the first (last) occurrence of character c in 
string s, or a NULL pointer if c does not occur in the string. The null character 
terminating a string is considered to be part of the string. 

Strpbrk returns a pointer to the first occurrence in string si of any character from 
string s2, or a NULL pointer if no character from s2 exists in si. 

Strspn ( strcspn ) returns the length of the initial segment of string si which con- 
sists entirely of characters from (not from) string s2. 

Strtok considers the string si to consist of a sequence of zero or more text tokens 
separated by spans of one or more characters from the separator string s2. The 
first call (with pointer si specified) returns a pointer to the first character of the 
first token, and will have written a null character into si immediately following 
the returned token. The function keeps track of its position in the string between 
separate calls, so that subsequent calls (which must be made with the first argu- 
ment a NULL pointer) will work through the string si immediately following 
that token. In this way subsequent calls will work through the string si until no 
tokens remain. The separator string s2 may be different from call to call. When 
no tok^n remains in si, a NULL pointer is returned. 

For user convenience, all these functions are declared in the optional <string.h> 
header file. 

SEE ALSO 

malloc(3C), malloc(3X). 
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CAVEATS 

Strcmp and strncmp are implemented by using the most natural character com- 
parison on the machine. Thus the sign of the value returned when one of the 
characters has its high-order bit set not the same in all implementations and 
should not be relied upon. 

Character movement is performed differently in different implementations. Thus 
overlapping moves may yield surprises. 
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NAME 

strtod, atof — convert string to double-precision number 
SYNOPSIS 

double strtod (str, ptr) 
char *str, **ptr; 

double atof (str) 
char *str; 

DESCRIPTION 

strtod returns as a double-precision floating-point number the value represented 
by the character string pointed to by str. The string is scanned up to the first 
unrecognized character. 

strtod recognizes an optional string of "white-space" characters [as defined by 
isspace in ctype( 3C)], then an optional sign, then a string of digits optionally 
containing a decimal point, then an optional e or E followed by an optional sign 
or space, followed by an integer. 

If the value of ptr is not (char **)NULL, a pointer to the character terminating the 
scan is returned in the location pointed to by ptr. If no number can be formed, 
*ptr is set to str, and zero is returned. 

Atof(str) is equivalent to strtod(str, (char **)NULL). 

SEE ALSO 

ctype(3C), scanf(3S), strtol(3C). 

DIAGNOSTICS 

If the correct value would cause overflow, ±huge (as defined in <math.h>) is 
returned (according to the sign of the value), and errno is set to erange. 

If the correct value would cause underflow, zero is returned and errno is set to 
ERANGE. 
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NAME 

strtol, atol, atoi — convert string to integer 
SYNOPSIS 

long strtol (str, ptr, base) 
char *str, **ptr; 
int base; 

long atol (str) 
char *str; 

int atoi (str) 
char *str; 

DESCRIPTION 

strtol returns as a long integer the value represented by the character string 
pointed to by str. The string is scanned up to the first character inconsistent 
with the base. Leading "white-space" characters [as defined by isspace in 
ctype( 3C)] are ignored. 

If the value of ptr is not (char **)NULL, a pointer to the character terminating the 
scan is returned in the location pointed to by ptr. If no integer can be formed, 
that location is set to str , and zero is returned. 

If base is positive (and not greater than 36), it is used as the base for conversion. 
After an optional leading sign, leading zeros are ignored, and "Ox" or "OX" is 
ignored if base is 16. 

If base is zero, the string itself determines the base thusly: After an optional 
leading sign a leading zero indicates octal conversion, and a leading "Ox" or 
"OX" hexadecimal conversion. Otherwise, decimal conversion is used. 

Truncation from long to int can, of course, take place upon assignment or by an 
explicit cast. 

Atol(str) is equivalent to strtol(str f (char **)NULL, 10). 

Atoi(str) is equivalent to (int) strtol(str, (char **)NULL, 10). 

SEE ALSO 

ctype(3C), scanf(3S), strtod(3C). 

CAVEAT 

Overflow conditions are ignored. 
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NAME 

swab — swap bytes 
SYNOPSIS 

void swab (from, to, nbytes) 
char *from, *to; 
int nbytes; 

DESCRIPTION 

swab copies nbytes bytes pointed to by from to the array pointed to by to, 
exchanging adjacent even and odd bytes. Nbytes should be even and non- 
negative. If nbytes is odd and positive swab uses nbytes— 1 instead. If nbytes is 
negative, swab does nothing. 
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NAME 

system — issue a shell command 
SYNOPSIS 

#include <stdio.h> 

int system (string) 
char *string; 

DESCRIPTION 4 

system causes the string to be given to sh( 1) as input, as if the string had been 
typed as a command at a terminal. The current process waits until the shell has 
completed, then returns the exit status of the shell. 

FILES 

/bin/sh 

SEE ALSO 

exec(2). 

sh(l) in the User's Reference Manual 
DIAGNOSTICS 

system forks to create a child process that in turn exec's /bin/sh in order to exe- 
cute string. If the fork or exec fails, system returns a negative value and sets 
errno. 
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NAME 

tmpfile — create a temporary file 
SYNOPSIS 

#include <stdio.h> 

FILE *tmpfile () 

DESCRIPTION 

tmpfile creates a temporary file using a name generated by tmpnam( 3S), and 
returns a corresponding FILE pointer. If the file cannot be opened, an error mes- 
sage is printed using perror( 3C), and a NULL pointer is returned. The file will 
automatically be deleted when the process using it terminates. The file is 
opened for update ("w+"). 

SEE ALSO 

creat(2), unlink(2), fopen(3S), mktemp(3C), perror(3C), stdio(3S), tmpnam(3S). 
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NAME 

tmpnam, tempnam — create a name for a temporary file 
SYNOPSIS 

#include <stdio.h> 

char * tmpnam (s) 
char *s; 

char *tempnam (dir, pfx) 
char *dir, *pfx; 

DESCRIPTION 

These functions generate file names that can safely be used for a temporary file. 

tmpnam always generates a file name using the path-prefix defined as P_tmpdir 
in the <stdio.h> header file. If s is NULL, tmpnam leaves its result in an 
internal static area and returns a pointer to that area. The next call to tmpnam 
will destroy the contents of the area. If s is not NULL, it is assumed to be the 
address of an array of at least Ltmpnam bytes, where Ltmpnam is a constant 
defined in <stdio.fi>; tmpnam places its result in that array and returns s. 

Tempnam allows the user to control the choice of a directory. The argument dir 
points to the name of the directory in which the file is to be created. If dir is 
NULL or points to a string that is not a name for an appropriate directory, the 
path-prefix defined as P tmpdir in the <stdio.h> header file is used. If that 
directory is not accessible, /tmp will be used as a last resort. This entire 
sequence can be up-staged by providing an environment variable TMPDIR in the 
user's environment, whose value is the name of the desired temporary-file direc- 
tory. 

Many applications prefer their temporary files to have certain favorite initial 
letter sequences in their names. Use the pfx argument for this. This argument 
may be NULL or point to a string of up to five characters to be used as the first 
few characters of the temporary-file name. 

Tempnam uses malloc( 3C) to get space for the constructed file name, and returns 
a pointer to this area. Thus, any pointer value returned from tempnam may 
serve as an argument to free [see malloc( 3C)]. If tempnam cannot return the 
expected result for any reason, i.e. malloc (3C) failed, or none of the above men- 
tioned attempts to find an appropriate directory was successful, a NULL pointer 
will be returned. 

NOTES 

These functions generate a different file name each time they are called. 

Files created using these functions and either fopen( 3S) or creat( 2) are temporary 
only in the sense that they reside in a directory intended for temporary use, and 
their names are unique. It is the user's responsibility to use unlink ( 2) to remove 
the file when its use is ended. 

SEE ALSO 

creat(2), unlink(2), fopen(3S), malloc(3C), mktemp(3C), tmpfile(3S). 
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CAVEATS 

If called more than 17,576 times in a single process, these functions will start 
recycling previously used names. 

Between the time a file name is created and the file is opened, it is possible for 
some other process to create a file with the same name. This can never happen 
if that other process is using these functions or mktemp, and the file names are 
chosen to render duplication by other means unlikely. 
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NAME 

tsearch, tfind, tdelete, twalk — manage binary search trees 
SYNOPSIS 

#include <search.h> 

char *tsearch ((char *) key, (char **) rootp, compar) 
int (*compar)( ); 

char *tfind ((char *) key, (char **) rootp, compar) 
int (*compar)( ); 

char *tdelete ((char *) key, (char **) rootp, compar) 
int (*compar)( ); 

void twalk ((char *) root, action) 
void (*action)( ); 

DESCRIPTION 

tsearch , tfind, tdelete, and twalk are routines for manipulating binary search trees. 
They are generalized from Knuth (6.2.2) Algorithms T and D. All comparisons 
are done with a user-supplied routine. This routine is called with two argu- 
ments, the pointers to the elements being compared. It returns an integer less 
than, equal to, or greater than 0, according to whether the first argument is to be 
considered less than, equal to or greater than the second argument. The com- 
parison function need not compare every byte, so arbitrary data may be con- 
tained in the elements in addition to the values being compared. 

tsearch is used to build and access the tree. Key is a pointer to a datum to be 
accessed or stored. If there is a datum in the tree equal to *key (the value 
pointed to by key), a pointer to this found datum is returned. Otherwise, *key is 
inserted, and a pointer to it returned. Only pointers are copied, so the calling 
routine must store the data. Rootp points to a variable that points to the root of 
the tree. A NULL value for the variable pointed to by rootp denotes an empty 
tree; in this case, the variable will be set to point to the datum which will be at 
the root of the new tree. 

Like tsearch, tfind will search for a datum in the tree, returning a pointer to it if 
found. However, if it is not found, tfind will return a NULL pointer. The argu- 
ments for tfind are the same as for tsearch. 

Tdelete deletes a node from a binary search tree. The arguments are the same as 
for tsearch. The variable pointed to by rootp will be changed if the deleted 
node was the root of the tree. Tdelete returns a pointer to the parent of the 
deleted node, or a NULL pointer if the node is not found. 

Twalk traverses a binary search tree. Root is the root of the tree to be traversed. 
(Any node in a tree may be used as the root for a walk below that node.) Action 
is the name of a routine to be invoked at each node. This routine is, in turn, 
called with three arguments. The first argument is the address of the node being 
visited. The second argument is a value from an enumeration data type typedef 
enum { preorder, postorder, endorder, leaf } VISIT; (defined in the <search.h> 
header file), depending on whether this is the first, second or third time that the 
node has been visited (during a depth-first, left-to-right traversal of the tree), or 
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whether the node is a leaf. The third argument is the level of the node in the 
tree, with the root being level zero. 

The pointers to the key and the root of the tree should be of type pointer-to- 
element, and cast to type pointer-to-character. Similarly, although declared as 
type pointer-to-character, the value returned should be cast into type pointer-to- 
element. 

EXAMPLE 

The following code reads in strings and stores structures containing a pointer to 
each string and a count of its length. It then walks the tree, printing out the 
stored strings and their lengths in alphabetical order. 

#include <search.h> 

#include <stdio.h> 

struct node { /* pointers to these are stored in the tree */ 

char * string; 
int length; 

}; 

char string_space[ 10000]; /* space to store strings */ 

struct node nodes[500]; /* nodes to store */ 

struct node *root = NULL; /* this points to the root */ 

main( ) 

{ 

char * strptr = string_space; 
struct node *nodeptr = nodes; 
void print_node( ), twalk( ); 
int i = 0, node_compare( ); 

while (gets(strptr) != NULL && i++ < 500) { 

/* set node */ 
nodeptr— > string = strptr; 
nodeptr—> length = strlen(strptr); 

/* put node into the tree */ 

(void) tsearch((char *)nodeptr, (char **) &root, 
node_compare); 

/* adjust pointers, so we don't overwrite tree */ 

strptr += nodeptr- > length + 1; 

nodeptr++; 

} 

twalk((char *)root, print node); 

/* 

This routine compares two nodes, based on an 
alphabetical ordering of the string field. 



352 




TSEARCH(3C) (C Programming Language Utilities) TSEARCH(3C) 

v 

int 

node_compare(nodel, node2) 
char model, *node2; 

{ 

return strcmp(((struct node *)nodel)—> string, 

((struct node *) node2)—> string); 

/* 

This routine prints out a node, the first time 
twalk encounters it. 

*/ 

void 

print_node(node, order, level) 
char **node; 

VISIT order; 
int level; 

{ 

if (order == preorder II order == leaf) { 

(void)printf(”string = %20s, length = %d\n", 

(♦((struct node **)node))-> string, 

(♦((struct node **)node))-> length); 

} 

SEE ALSO 

bsearch(3C), hsearch(3C), lsearch(3C). 

DIAGNOSTICS 

A NULL pointer is returned by tsearch if there is not enough space available to 
create a new node. 

A NULL pointer is returned by tfind and tdelete if rootp is NULL on entry. 

If the datum is found, both tsearch and tfind return a pointer to it. If not, tfind 
returns NULL, and tsearch returns a pointer to the inserted item. 

WARNINGS 

The root argument to twalk is one level of indirection less than the rootp argu- 
ments to tsearch and tdelete. 

There are two nomenclatures used to refer to the order in which tree nodes are 
visited, tsearch uses preorder, postorder and endorder to respectively refer to 
visting a node before any of its children, after its left child and before its right, 
and after both its children. The alternate nomenclature uses preorder, inorder 
and postorder to refer to the same visits, which could result in some confusion 
over the meaning of postorder. 

CAVEAT 

If the calling function alters the pointer to the root, results are unpredictable. 
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NAME 

ttyname, isatty — find name of a terminal 
SYNOPSIS 

char *ttyname (Hides) 
int Hides; 

int isatty (Hides) 
int fildes; 

DESCRIPTION 

ttyname returns a pointer to a string containing the null-terminated path name of 
the terminal device associated with file descriptor fildes. 

Isatty returns 1 if fildes is associated with a terminal device, 0 otherwise. 

FILES 

/dev/* 

DIAGNOSTICS 

ttyname returns a NULL pointer if fildes does not describe a terminal device in 
directory /dev. 

CAVEAT 

The return value points to static data whose content is overwritten by each call. 



354 




TTYSLOT(3C) 



(C Programming Language Utilities) 



TTYSLOT(3C) 



NAME 

ttyslot — find the slot in the utmp file of the current user 

SYNOPSIS 

int ttyslot ( ) 

DESCRIPTION 

ttyslot returns the index of the current user's entry in the /etc/utmp file. This is 
accomplished by actually scanning the file /etc/inittab for the name of the ter- 
minal associated with the standard input, the standard output, or the error 
output (0, 1 or 2). 

FILES 

/etc/inittab 

/etc/utmp 

SEE ALSO 

getut(3C), ttyname(3C). 

DIAGNOSTICS 

A value of 0 is returned if an error was encountered while searching for the ter- 
minal name or if none of the above file descriptors is associated with a terminal 
device. 



355 




UNGETC(3S) 



(C Programming Language Utilities) 



UNGETC(3S) 



NAME 

ungetc — push character back into input stream 
SYNOPSIS 

#include <stdio.h> 

int ungetc (c, stream) 
int C; 

FILE ^stream; 

DESCRIPTION 

ungetc inserts the character c into the buffer associated with an input stream. 
That character, c, will be returned by the next getc( 3S) call on that stream, 
ungetc returns c, and leaves the file stream unchanged. 

One character of pushback is guaranteed, provided something has already been 
read from the stream and the stream is actually buffered. 

If c equals EOF, ungetc does nothing to the buffer and returns EOF. 

Fseek( 3S) erases all memory of inserted characters. 

SEE ALSO 

fseek(3S), getc(3S), setbuf(3S), stdio(3S). 

DIAGNOSTICS 

ungetc returns EOF if it cannot insert the character. 

BUGS 

When stream is stdin, one character may be pushed back onto the buffer without 
a previous read statement. 
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NAME 

vprintf, vfprintf, vsprintf — print formatted output of a varargs argument list 
SYNOPSIS 

#include <stdio.h> 

#include <varargs.h> 

int vprintf (format, ap) 
char ^format; 
va list ap; 

int vfprintf (stream, format, ap) 

FILE *stream; 
char * for mat; 
valist ap; 

int vsprintf (s, format, ap) 
char *s, *format; 
va list ap; 

DESCRIPTION 

vprintf, vfprintf, and vsprintf are the same as printf, fprintf, and sprintf respec- 
tively, except that instead of being called with a variable number of arguments, 
they are called with an argument list as defined by varargs(5). 

EXAMPLE 

The following demonstrates the use of vfprintf to write an error routine. 

#include <stdio.h> 

#include <varargs.h> 



/* 

* error should be called like 

* error(function_name, format, argl, arg2...); */ 

/♦VARARGS*/ 

void 

error(va_alist) 

/* Note that the function_name and format arguments cannot be 

* separately declared because of the definition of varargs. */ 
va_dcl 

{ 

va list args; 
char *fmt; 

va_start(args); 

/* print out name of function causing error */ 
(void)fprintf(stderr, "ERROR in %s: ", va_arg(args, char *)); 
fmt = va_arg(args, char *); 
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/* print out remainder of message */ 
(void)vfprintf(stderr, fmt, args); 
va_end(args); 

(void)abort( ); 

SEE ALSO 

printf(3S), varargs(5). 
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NAME 

bessel: jO, jl, jn, yO, yl, yn — Bessel functions 
SYNOPSIS 

#include <math.h> 

double jO (x) 
double x; 

double jl (x) 
double x; 

double jn (n, x) 
int n; 
double x; 

double yO (x) 
double x; 

double yl (x) 
double x; 

double yn (n, x) 
int n; 
double x; 

DESCRIPTION 

JO and jl return Bessel functions of x of the first kind of orders 0 and 1 respec- 
tively. Jn returns the Bessel function of x of the first kind of order n. 

YO and yl return Bessel functions of x of the second kind of orders 0 and 1 
respectively. Yn returns the Bessel function of x of the second kind of order n. 
The value of x must be positive. 

SEE ALSO 

matherr(3M). 

DIAGNOSTICS 

Non-positive arguments cause yO, yl and yn to return the value -HUGE and to 
set errno to EDOM. In addition, a message indicating DOMAIN error is printed 
on the standard error output. 

Arguments too large in magnitude cause jO, jl, yO and yl to return zero and to 
set errno to ERANGE. In addition, a message indicating TLOSS error is printed 
on the standard error output. 

These error-handling procedures may be changed with the function matherr( 3M). 
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NAME 

erf, erfc — error function and complementary error function 
SYNOPSIS 

#include <math.h> 

double erf (x) 
double x; 

double erfc (x) 
double x; 



DESCRIPTION 

erf returns the error function of x, defined as 




erfc, which returns 1.0 — erf(x), is provided because of the extreme loss of rela- 
tive accuracy if erf(x) is called for large x and the result subtracted from 1.0 (e.g., 
for x = 5, 12 places are lost). 



SEE ALSO 

exp(3M). 
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NAME 

exp, log, loglO, pow, sqrt — exponential, logarithm, power, square root functions 
SYNOPSIS 

#include <math.h> 

double exp (x) 
double x; 

double log (x) 
double x; 

double loglO (x) 
double x; 

double pow (x, y) 
double x, y; 

double sqrt (x) 
double x; 

DESCRIPTION 

exp returns e x . 

Log returns the natural logarithm of x. The value of x must be positive. 

LoglO returns the logarithm base ten of x. The value of x must be positive. 

Pow returns . If x is zero, y must be positive. If x is negative, y must be an 
integer. 

Sqrt returns the non-negative square root of x. The value of x may not be nega- 
tive. 

SEE ALSO 

hypot(3M), matherr(3M), sinh(3M). 

DIAGNOSTICS 

exp returns HUGE when the correct value would overflow, or 0 when the correct 
value would underflow, and sets errno to ERANGE. 

Log and loglO return -HUGE and set errno to EDOM when x is non-positive. A 
message indicating DOMAIN error (or SING error when x is 0) is printed on the 
standard error output. 

Pow returns 0 and sets errno to EDOM when x is 0 and y is non-positive, or 
when x is negative and y is not an integer. In these cases a message indicating 
DOMAIN error is printed on the standard error output. When the correct value 
for pow would overflow or underflow, pow returns ±HUGE or 0 respectively, 
and sets errno to ERANGE. 

Sqrt returns 0 and sets errno to EDOM when x is negative. A message indicating 
DOMAIN error is printed on the standard error output. 

These error-handling procedures may be changed with the function matherr( 3M). 
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NAME 

floor, ceil, fmod, fabs — floor, ceiling, remainder, absolute value functions 
SYNOPSIS 

#include <math.h> 

double floor (x) 
double x; 

double ceil (x) 
double x; 

double fmod (x, y) 
double x, y; 

double fabs (x) 
double x; 

DESCRIPTION 

floor returns the largest integer (as a double-precision number) not greater than 

x. 

Ceil returns the smallest integer not less than x. 

Fmod returns the floating-point remainder of the division of x by y: zero if y is 
zero or if x/y would overflow; otherwise the number / with the same sign as x, 
such that x = iy + / for some integer i, and \f\ < \y\. 

Fabs returns the absolute value of x, |x|. 

SEE ALSO 

abs(3C). 
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NAME 

gamma — log gamma function 
SYNOPSIS 

#include <math.h> 

double gamma (x) 
double x; 

extern int signgam; 

DESCRIPTION 

QO 

gamma returns ln(|r(x)|), where T(x) is defined as §e~ l t x ~ l dt. The sign of 

o 

T(x) is returned in the external integer signgam. The argument x may not be a 
non-positive integer. 

The following C program fragment might be used to calculate T: 

if ((y * gamma(x)) > LNMAXDOUBLE) 
error(); 

y * signgam * exp{y); 

where LN_MAXDOUBLE is the least value that causes exp( 3M) to return a range 
error, and is defined in the <values.h> header file. 

SEE ALSO 

exp(3M), matherr(3M), values(5). 

DIAGNOSTICS 

For non-negative integer arguments HUGE is returned, and errno is set to EDOM. 
A message indicating SING error is printed on the standard error output. 

If the correct value would overflow, gamma returns HUGE and sets errno to 
ERANGE. 

These error-handling procedures may be changed with the function matherr( 3M). 
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NAME 

hypot — Euclidean distance function 
SYNOPSIS 

#include <math.h> 

double hypot (x, y) 
double x, y; 

DESCRIPTION 

hypot returns 

sqrt(x * x + y * y), 

taking precautions against unwarranted overflows. 

SEE ALSO 

matherr(3M). 

DIAGNOSTICS 

When the correct value would overflow, hypot returns HUGE and sets errno to 
ERANGE. 

These error-handling procedures may be changed with the function matherr( 3M). 
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NAME 

matherr — error-handling function 
SYNOPSIS 

#include <math.h> 

int matherr (x) 
struct exception *x ; 

DESCRIPTION 

matherr is invoked by functions in the Math Library when errors are detected. 
Users may define their own procedures for handling errors, by including a func- 
tion named matherr in their programs, matherr must be of the form described 
above. When an error occurs, a pointer to the exception structure x will be 
passed to the user-supplied matherr function. This structure, which is defined in 
the <math.h> header file, is as follows: 

struct exception { 
int type; 
char *name; 

double argl, arg2, retval; 

}; 

The element type is an integer describing the type of error that has occurred, 
from the following list of constants (defined in the header file): 

DOMAIN argument domain error 

SING argument singularity 

OVERFLOW overflow range error 

UNDERFLOW underflow range error 

TLOSS total loss of significance 

PLOSS partial loss of significance 

The element name points to a string containing the name of the function that 
incurred the error. The variables argl and argl are the arguments with which 
the function was invoked. Retval is set to the default value that will be returned 
by the function unless the user's matherr sets it to a different value. 

If the user's matherr function returns non-zero, no error message will be printed, 
and errno will not be set. 

If matherr is not supplied by the user, the default error-handling procedures, 
described with the math functions involved, will be invoked upon error. These 
procedures are also summarized in the table below. In every case, errno is set to 
EDOM or ERANGE and the program continues. 

EXAMPLE 

#include <math.h> 
int 

matherr(x) 

register struct exception *x; 

switch (x— >type) { 
case DOMAIN: 
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/♦ change sqrt to return sqrt(-argl), not 0 */ 
if (!strcmp(x— > name, "sqrt”)) { 

x— >retval ==* sqrt(— x— >argl); 

return (0); /* print message and set errno */ 

case SING: 

/* all other domain or sing errors, print message and abort * / 
fprintf(stderr, "domain error in %s\n", x— >name); 
abort( ); 
case PLOSS: 

/* print detailed error message */ 
fprintf(stderr, "loss of significance in %s(%g) * %g\n", 
x— >name, x— >argl, x->retval); 
return (1); /* take no other action */ 

return (0); /* all other errors, execute default procedure */ 



DEFAULT ERROR HANDLING PROCEDURES 









Types 


of Errors 






type 


DOMAIN 


SING 


OVERFLOW 


UNDERFLOW 


TLOSS 


PLOSS 


errno 


EDOM 


EDOM 


ERANGE 


ERANGE 


ERANGE 


ERANGE 


BESSEL: 


- 


- 


- 


- 


M, 0 


* 


yO, yl, yn (arg < 0) 


M, -H 


- 


- 


- 


- 


- 


EXP: 


- 


- 


H 


0 


- 


- 


LOG, LOGIO: 














(arg < 0) 


M, -H 


- 


- 


- 


- 


- 


(arg - 0) 


- 


M, -H 


- 


- 


- 


- 


POW: 


- 


- 


±H 


0 


- 


- 


neg ** non-int 


M, 0 


- 


- 


- 


- 


- 


0 ** non-pos 














SQRT: 


M, 0 


- 


- 


- 


- 


- 


GAMMA: 


- 


M, H 


H 


- 


- 




HYPOT: 


- 


- 


H 


- 


- 


- 


SINH: 


- 


- 


±H 


- 


- 


- 


COSH: 


- 


- 


H 


- 


- 


- 


SIN, COS, TAN: - 


- 


- 


- 


M, 0 


* 




ASIN, ACOS, ATAN2: M, 0 


- 


- 


- 


- 


- 





ABBREVIATIONS 

* As much as possible of the value is returned. 
M Message is printed (EDOM error). 

H HUGE is returned. 

— H —HUGE is returned. 

±H HUGE or -HUGE is returned. 

0 0 is returned. 
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NAME 

sinh, cosh, tanh — hyperbolic functions 
SYNOPSIS 

#include <math.h> 

double sinh (x) 
double x; 

double cosh (x) 
double x; 

double tanh (x) 
double x; 

DESCRIPTION 

sink, cosh, and tanh return, respectively, the hyberbolic sine, cosine and tangent 
of their argument. 

SEE ALSO 

matherr(3M). 

DIAGNOSTICS 

sinh and cosh return HUGE (and sinh may return -HUGE for negative x) when 
the correct value would overflow and set errno to ERANGE. 

These error-handling procedures may be changed with the function matherr( 3M). 
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NAME 

trig: sin, cos, tan, asin, acos, atan, atan2 — trigonometric functions 
SYNOPSIS 

#include <math.h> 

double sin (x) 
double x; 

double cos (x) 
double x; 

double tan (x) 
double x; 

double asin (x) 
double x; 

double acos (x) 
double x; 

double atan (x) 
double x; 

d' able atan2 (y, x) 
double y, x; 

DESCRIPTION 

Sin, cos and tan return respectively the sine, cosine and tangent of their argu- 
ment, x , measured in radians. 

Asin returns the arcsine of x , in the range [— 7r/2,7r/2]. 

Acos returns the arccosine of x, in the range [0,7r]. 

Atan returns the arctangent of x, in the range [— t/2,tt/2]. 

Atan! returns the arctangent of y /x, in the range (— 7r,7r], using the signs of both 
arguments to determine the quadrant of the return value. 

SEE ALSO 

matherr(3M). 

DIAGNOSTICS 

Sin, cos, and tan lose accuracy when their argument is far from zero. For argu- 
ments sufficiently large, these functions return zero when there would otherwise 
be a complete loss of significance. In this case a message indicating TLOSS error 
is printed on the standard error output. For less extreme arguments causing par- 
tial loss of significance, a PLOSS error is generated but no message is printed. In 
both cases, errno is set to ERANGE. 

If the magnitude of the argument of asin or acos is greater than one, or if both 
arguments of atan2 are zero, zero is returned and errno is set to EDOM. In addi- 
tion, a message indicating DOMAIN error is printed on the standard error output. 

These error-handling procedures may be changed with the function matherr( 3M). 
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NAME 

t_accept — accept a connect request 
SYNOPSIS 

#include <tiuser.h> 

int taccept(fd, resfd, call) 

int fd; 

int resfd; 

struct t_call *call; 

DESCRIPTION 

This function is issued by a transport user to accept a connect request. Fd 
identifies the local transport endpoint where the connect indication arrived, resfd 
specifies the local transport endpoint where the connection is to be established, 
and call contains information required by the transport provider to complete the 
connection. Call points to a t_call structure which contains the following 
members: 

struct netbuf addr; 
struct netbuf opt; 
struct netbuf udata; 
int sequence; 

Netbuf is described in intro( 3). In call, addr is the address of the caller, opt indi- 
cates any protocol-specific parameters associated with the connection, udata 
points to any user data to be returned to the caller, and sequence is the value 
returned by tjisten that uniquely associates the response with a previously 
received connect indication. 

A transport user may accept a connection on either the same, or on a different, 
local transport endpoint than the one on which the connect indication arrived. 
If the same endpoint is specified (i.e., resfd— fd), the connection can be accepted 
unless the following condition is true: The user has received other indications on 
that endpoint but has not responded to them (with tjiccept or t_snddis). For this 
condition, t_accept will fail and set t_errno to TBADF. 

If a different transport endpoint is specified (resfd\=fd), the endpoint must be 
bound to a protocol address and must be in the T IDLE state [see t_getstate( 3N)] 
before the t_accept is issued. 

For both types of endpoints, tjiccept will fail and set t_errno to TLOOK if there 
are indications (e.g., a connect or disconnect) waiting to be received on that end- 
point. 

The values of parameters specified by opt and the syntax of those values are 
protocol specific. The udata argument enables the called transport user to send 
user data to the caller and the amount of user data must not exceed the limits 
supported by the transport provider as returned by tj)pen or t_getinfo. If the len 
[see netbuf in intro{ 3)] field of udata is zero, no data will be sent to the caller. 

On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint, or the user is illegally accepting a connection on 
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the same transport endpoint on which the connect indica- 
tion arrived. 


[TOUTSTATE] 


The function was issued in the wrong sequence on the 
transport endpoint referenced by fd, or the transport end- 
point referred to by resfd is not in the T IDLE state. 


[TACCES] 


The user does not have permission to accept a connection 
on the responding transport endpoint or use the specified 
options. 


[TBADOPT] 


The specified options were in an incorrect format or con- 
tained illegal information. 


[TB ADD AT A] 


The amount of user data specified was not within the 
bounds allowed by the transport provider. 


[TBADSEQ] 


An invalid sequence number was specified. 


[TLOOK] 


An asynchronous event has occurred on the transport end- 
point referenced by fd and requires immediate attention. 


[TNOTSUPPORT] 


This function is not supported by the underlying transport 
provider. 


[TSYSERR] 


A system error has occurred during execution of this func- 
tion. 



SEE ALSO 

intro(3), t_connect(3N), t_getstate(3N), t_listen(3N), t_open(3N), 
t_rcvconnect(3N). 

Network Programmer's Guide. 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of — 1 
is returned and t errno is set to indicate the error. 
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NAME 

t_alloc — allocate a library structure 
SYNOPSIS 

#include <tiuser.h> 

char *t_alloc(fd, structtype, fields) 
int fd; 

int structtype; 
int fields; 

DESCRIPTION 

The tjilloc function dynamically allocates memory for the various transport 
function argument structures as specified below. This function will allocate 
memory for the specified structure, and will also allocate memory for buffers 
referenced by the structure. 

The structure to allocate is specified by struct Jype, and can be one of the fol- 
lowing: 

T BIND struct tjbind 

T CALL struct t_call 

T OPTMGMT struct t_optmgmt 

T DIS struct t_discon 

T UNITDATA struct t_unitdata 

TUDERROR struct t_uderr 

TINFO struct t info 

where each of these structures may subsequently be used as an argument to one 
or more transport functions. 

Each of the above structures, except T INFO, contains at least one field of type 
struct netbuf. Netbuf is described in intro( 3). For each field of this type, the user 
may specify that the buffer for that field should be allocated as well. The fields 
argument specifies this option, where the argument is the bitwise-OR of any of 
the following: 

T_ADDR The addr field of the tjoind, tjall, tjinitdata, or tjiderr structures. 

T OPT The opt field of the t_optmgmt, t_call, tjinitdata, or t_uderr structures. 
TJJDATA The udata field of the t_call, t_discon f or tjinitdata structures. 

T ALL All relevant fields of the given structure. 

For each field specified in fields, tjdloc will allocate memory for the buffer asso- 
ciated with the field, and initialize the buf pointer and maxlen [see netbuf in 
intro( 3) for description of buf and maxlen] field accordingly. The length of the 
buffer allocated will be based on the same size information that is returned to 
the user on tjpen and t_getinfo. Thus, fd must refer to the transport endpoint 
through which the newly allocated structure will be passed, so that the 
appropriate size information can be accessed. If the size value associated with 
any specified field is -1 or -2 (see tj)pen or t_getinfo), tjdloc will be unable to 
determine the size of the buffer to allocate and will fail, setting tjrrno to 
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TSYSERR and errno to EINVAL. For any field not specified in fields, buf will be 
set to NULL and maxlen will be set to zero. 

Use of t_alloc to allocate structures will help ensure the compatibility of user 
programs with future releases of the transport interface. 

On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport end- 

point. 

[TSYSERR] A system error has occurred during execution of this function. 

SEE ALSO 

intro(3), t_free(3N), t_getinfo(3N), t_open(3N). 

Network Programmer's Guide. 

DIAGNOSTICS 

On successful completion, tjilloc returns a pointer to the newly allocated struc- 
ture. On failure, NULL is returned. 
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NAME 

t_bind — bind an address to a transport endpoint 
SYNOPSIS 

#include <tiuser.h> 

int t_bind(fd, req, ret) 
int fd; 

struct t bind *req; 
struct t bind *ret; 

DESCRIPTION 

This function associates a protocol address with the transport endpoint specified 
by fd and activates that transport endpoint. In connection mode, the transport 
provider may begin accepting or requesting connections on the transport end- 
point. In connectionless mode, the transport user may send or receive data units 
through the transport endpoint. 

The req and ret arguments point to a tjoind structure containing the following 
members: 

struct netbuf addr; 
unsigned qlen; 

Netbuf is described in intro( 3). The addr field of the t_bind structure specifies a 
protocol address and the qlen field is used to indicate the maximum number of 
outstanding connect indications. 

Req is used to request that an address, represented by the netbuf structure, be 
bound to the given transport endpoint. Len [see netbuf in intro( 3); also for buf 
and maxlen] specifies the number of bytes in the address and buf points to the 
address buffer. Maxlen has no meaning for the req argument. On return, ret 
contains the address that the transport provider actually bound to the transport 
endpoint; this may be different from the address specified by the user in req. In 
ret, the user specifies maxlen which is the maximum size of the address buffer 
and buf which points to the buffer where the address is to be placed. On return, 
len specifies the number of bytes in the bound address and buf points to the 
bound address. If maxlen is not large enough to hold the returned address, an 
error will result. 

If the requested address is not available, or if no address is specified in req (the 
len field of addr in req is zero) the transport provider will assign an appropriate 
address to be bound, and will return that address in the addr field of ret. The 
user can compare the addresses in req and ret to determine whether the tran- 
sport provider bound the transport endpoint to a different address than that 
requested. 

Req may be NULL if the user does not wish to specify an address to be bound. 
Here, the value of qlen is assumed to be zero, and the transport provider must 
assign an address to the transport endpoint. Similarly, ret may be NULL if the 
user does not care what address was bound by the provider and is not interested 
in the negotiated value of qlen. It is valid to set req and ret to NULL for the 
same call, in which case the provider chooses the address to bind to the tran- 
sport endpoint and does not return that information to the user. 



373 




T_BIND(3N) 



(Networking Support Utilities) 



T_BIND(3N) 



The qlen field has meaning only when initializing a connection-mode service. It 
specifies the number of outstanding connect indications the transport provider 
should support for the given transport endpoint. An outstanding connect indica- 
tion is one that has been passed to the transport user by the transport provider. 
A value of qlen greater than zero is only meaningful when issued by a passive 
transport user that expects other users to call it. The value of qlen will be nego- 
tiated by the transport provider and may be changed if the transport provider 
cannot support the specified number of outstanding connect indications. On 
return, the qlen field in ret will contain the negotiated value. 

This function allows more than one transport endpoint to be bound to the same 
protocol address (however, the transport provider must support this capability 
also), but it is not allowable to bind more than one protocol address to the same 
transport endpoint. If a user binds more than one transport endpoint to the 
same protocol address, only one endpoint can be used to listen for connect indi- 
cations associated with that protocol address. In other words, only one t_bind 
for a given protocol address may specify a value of qlen greater than zero. In 
this way, the transport provider can identify which transport endpoint should be 
notified of an incoming connect indication. If a user attempts to bind a protocol 
address to a second transport endpoint with a value of qlen greater than zero, 
the transport provider will assign another address to be bound to that endpoint. 
If a user accepts a connection on the transport endpoint that is being used as the 
listening endpoint, the bound protocol address will be found to be busy for the 
duration of that connection. No other transport endpoints may be bound for 
listening while that initial listening endpoint is in the data transfer phase. This 
will prevent more than one transport endpoint bound to the same protocol 
address from accepting connect indications. 

On failure, t_errno may be set to one of the following: 



[TBADF] 

[TOUTSTATE] 

[TBADADDR] 

[TNOADDR] 

[TACCES] 



The specified file descriptor does not refer to a transport 
endpoint. 

The function was issued in the wrong sequence. 

The specified protocol address was in an incorrect format or 
contained illegal information. 

The transport provider could not allocate an address. 

The user does not have permission to use the specified 
address. 



[TBUFOVFLW] The number of bytes allowed for an incoming argument is 

not sufficient to store the value of that argument. The pro- 
vider's state will change to T IDLE and the information to 
be returned in ret will be discarded. 

[TSYSERR] A system error has occurred during execution of this func- 

tion. 
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SEE ALSO 

intro(3), t_open(3N), t_optmgmt(3N), t_unbind(3N). 

Network Programmer's Guide. 

DIAGNOSTICS 

t_bind returns 0 on success and -1 on failure and t_errno is set to indicate the 
error. 
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NAME 

t_close — close a transport endpoint 
SYNOPSIS 

#include <tiuser.h> 

int t close(fd) 
int fd; 

DESCRIPTION 

The t_close function informs the transport provider that the user is finished with 
the transport endpoint specified by fd, and frees any local library resources asso- 
ciated with the endpoint. In addition, t_close closes the file associated with the 
transport endpoint. 

t_close should be called from the T_UNBND state [see t_getstate (3N)]. However, 
this function does not check state information, so it may be called from any state 
to close a transport endpoint. If this occurs, the local library resources associ- 
ated with the endpoint will be freed automatically. In addition, close( 2) will be 
issued for that file descriptor; the close will be abortive if no other process has 
that file open, and will break any transport connection that may be associated 
with that endpoint. 

On failure, t_errno may be set to the following: 

[TBADF] The specified file descriptor does not refer to a transport endpoint. 

SEE ALSO 

t_getstate(3N), t_open(3N), t_unbind(3N). 

Network Programmer's Guide. 

DIAGNOSTICS 

t_close returns 0 on success and -1 on failure and t errno is set to indicate the 
error. 
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NAME 

t_connect — establish a connection with another transport user 
SYNOPSIS 

#include <tiuser.h> 

int t_connect(fd, sndcall, rcvcall) 
int fd; 

struct tcall *sndcall; 
struct t call *rcvcall; 

DESCRIPTION 

This function enables a transport user to request a connection to the specified 
destination transport user. Fd identifies the local transport endpoint where com- 
munication will be established, while sndcall and rcvcall point to a t_call struc- 
ture which contains the following members: 

struct netbuf addr; 
struct netbuf opt; 
struct netbuf udata; 
int sequence; 

Sndcall specifies information needed by the transport provider to establish a con- 
nection and rcvcall specifies information that is associated with the newly esta- 
blished connection. 

Netbuf is described in intro( 3). In sndcall , addr specifies the protocol address of 
the destination transport user, opt presents any protocol-specific information that 
might be needed by the transport provider, udata points to optional user data 
that may be passed to the destination transport user during connection establish- 
ment, and sequence has no meaning for this function. 

On return in rcvcall, addr returns the protocol address associated with the 
responding transport endpoint, opt presents any protocol-specific information 
associated with the connection, udata points to optional user data that may be 
returned by the destination transport user during connection establishment, and 
sequence has no meaning for this function. 

The opt argument implies no structure on the options that may be passed to the 
transport provider. The transport provider is free to specify the structure of any 
options passed to it. These options are specific to the underlying protocol of the 
transport provider. The user may choose not to negotiate protocol options by 
setting the len field of opt to zero. In this case, the provider may use default 
options. 

The udata argument enables the caller to pass user data to the destination tran- 
sport user and receive user data from the destination user during connection 
establishment. However, the amount of user data must not exceed the limits 
supported by the transport provider as returned by t_open (3N) or t_getinfo (3N). 
If the len [see netbuf in intro( 3)] field of udata is zero in sndcall, no data will be 
sent to the destination transport user. 

On return, the addr, opt, and udata fields of rcvcall will be updated to reflect 
values associated with the connection. Thus, the maxlen [see netbuf in intro( 3)] 
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field of each argument must be set before issuing this function to indicate the 
maximum size of the buffer for each. However, rev call may be NULL, in which 
case no information is given to the user on return from t_connect. 

By default, t_connect executes in synchronous mode, and will wait for the desti- 
nation user's response before returning control to the local user. A successful 
return (i.e. return value of zero) indicates that the requested connection has been 
established. However, if ONDELAY is set (via t_open or fcntl), t_connect executes 
in asynchronous mode. In this case, the call will not wait for the remote user's 
response, but will return control immediately to the local user and return -1 with 
t_errno set to TNODATA to indicate that the connection has not yet been esta- 
blished. In this way, the function simply initiates the connection establishment 
procedure by sending a connect request to the destination transport user. 



On failure, t_errno may be set to one of the following: 



[TBADF] 

[TOUTSTATE] 

[TNODATA] 

[TBADADDR] 

[TBADOPT] 

[TBADDATA] 

[TACCES] 

[TBUFOVFLW] 



The specified file descriptor does not refer to a transport 
endpoint. 

The function was issued in the wrong sequence. 

O NDELAY was set, so the function successfully initiated 
the connection establishment procedure, but did not wait 
for a response from the remote user. 

The specified protocol address was in an incorrect format or 
contained illegal information. 

The specified protocol options were in an incorrect format 
or contained illegal information. 

The amount of user data specified was not within the 
bounds allowed by the transport provider. 

The user does not have permission to use the specified 
address or options. 

The number of bytes allocated for an incoming argument is 
not sufficient to store the value of that argument. If exe- 
cuted in synchronous mode, the provider's state, as seen by 
the user, changes to T_DATAXFER, and the connect indica- 
tion information to be returned in rcvcall is discarded. 



[TLOOK] 

[TNOTSUPPORT] 

[TSYSERR] 



An asynchronous event has occurred on this transport end- 
point and requires immediate attention. 

This function is not supported by the underlying transport 
provider. 

A system error has occurred during execution of this func- 
tion. 



SEE ALSO 

intro(3), t_accept(3N), t_getinfo(3N), t_listen(3N), t_open(3N), t_optmgmt(3N), 
t_rc vconnect(3 N) . 

Network Programmer's Guide. 
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DIAGNOSTICS 

t_connect returns 0 on success and -1 on failure and t_errno is set to indicate the 
error. 
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NAME 

t error — produce error message 
SYNOPSIS 

#include <tiuser.h> 

void t error(errmsg) 
char *errmsg; 
extern int t errno; 
extern char *t errlist[]; 
extern int t nerr; 

DESCRIPTION 

The t_error function produces a message on the standard error output which 
describes the last error encountered during a call to a transport function. The 
argument string errmsg is a user-supplied error message that gives context to the 
error. t_error prints the user-supplied error message followed by a colon and a 
standard error message for the current error defined in t_errno. To simplify 
variant formatting of messages, the array of message strings t_errlist is provided; 
t_errno can be used as an index in this table to get the message string without 
the newline. Tjierr is the largest message number provided for in the t_errlist 
table. 

T_errno is only set when an error occurs and is not cleared on successful calls. 
EXAMPLE 

If a t_connect function fails on transport endpoint fd2 because a bad address was 
given, the following call might follow the failure: 

t_error("t_connect failed on fd2"); 

The diagnostic message to be printed would look like: 

t_connect failed on fd2: Incorrect transport address format 

where "Incorrect transport address format" identifies the specific error that 
occurred, and "t_connect failed on fd2" tells the user which function failed on 
which transport endpoint. 

SEE ALSO 

Network Programmer's Guide. 
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NAME 

t_free — free a library structure 
SYNOPSIS 

#include <tiuser.h> 

int t free(ptr, struct type) 

char *ptr; 

int struct type; 

DESCRIPTION 

The tjree function frees memory previously allocated by tjilloc. This function 
will free memory for the specified structure, and will also free memory for 
buffers referenced by the structure. 

Ptr points to one of the six structure types described for tjilloc, and struct Jype 
identifies the type of that structure which can be one of the following: 

T BIND struct tjbind 

T_CALL struct t_call 

TOPTMGMT struct toptmgmt 

T DIS struct t_discon 

T UNITDATA struct t_unitdata 

TUDERROR struct t_uderr 

T INFO struct t_info 

where each of these structures is used as an argument to one or more transport 
functions. 

tjree will check the addr, opt, and udata fields of the given structure (as 
appropriate), and free the buffers pointed to by the buf field of the netbuf [see 
intro( 3)] structure. If buf is NULL, tjree will not attempt to free memory. After 
all buffers are freed, tjree will free the memory associated with the structure 
pointed to by ptr. 

Undefined results will occur if ptr or any of the buf pointers points to a block of 
memory that was not previously allocated by tjilloc. 

On failure, t_errno may be set to the following: 

[TSYSERR] A system error has occurred during execution of this function. 

SEE ALSO 

intro(3), t_alloc(3N). 

Network Programmer's Guide. 

DIAGNOSTICS 

tjree returns 0 on success and -1 on failure and t_errno is set to indicate the 
error. 
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NAME 

t^getinfo — get protocol-specific service information 
SYNOPSIS 

#include <tiuser.h> 

int t j^etinfoffd, info) 
int fd; 

struct t info ♦info; 

DESCRIPTION 

This function returns the current characteristics of the underlying transport pro- 
tocol associated with file descriptor fd. The info structure is used to return the 
same information returned by t_open. This function enables a transport user to 
access this information during any phase of communication. 

This argument points to a tjnfo structure which contains the following 
members: 

long addr; /* max size of the transport protocol address */ 

long options; /* max number of bytes of protocol -specific options */ 

long tsdu; /* max size of a transport service data unit (TSDU) */ 

long etsdu; /* max size of an expedited transport service data unit (ETSDU) */ 

long connect; /* max amount of data allowed on connection establishment 
functions */ 

long discon; /* max amount of data allowed on t_snddis and tjcvdis functions */ 
long servtype; /* service type supported by the transport provider */ 

The values of the fields have the following meanings: 

addr A value greater than or equal to zero indicates the maximum size 

of a transport protocol address; a value of -1 specifies that there 
is no limit on the address size; and a value of -2 specifies that 
the transport provider does not provide user access to transport 
protocol addresses. 

options A value greater than or equal to zero indicates the maximum 

number of bytes of protocol-specific options supported by the 
provider; a value of -1 specifies that there is no limit on the 
option size; and a value of -2 specifies that the transport provider 
does not support user-settable options. 

tsdu A value greater than zero specifies the maximum size of a tran- 

sport service data unit (TSDU); a value of zero specifies that the 
transport provider does not support the concept of TSDU, 
although it does support the sending of a data stream with no 
logical boundaries preserved across a connection; a value of -1 
specifies that there is no limit on the size of a TSDU; and a value 
of -2 specifies that the transfer of normal data is not supported 
by the transport provider. 

et&du A value greater than zero specifies the maximum size of an 

expedited transport service data unit (ETSDU); a value of zero 
specifies that the transport provider does not support the concept 
of ETSDU, although it does support the sending of an expedited 
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data stream with no logical boundaries preserved across a con- 
nection; a value of -1 specifies that there is no limit on the size 
of an ETSDU; and a value of -2 specifies that the transfer of 
expedited data is not supported by the transport provider. 

connect A value greater than or equal to zero specifies the maximum 

amount of data that may be associated with connection establish- 
ment functions; a value of -1 specifies that there is no limit on 
the amount of data sent during connection establishment; and a 
value of -2 specifies that the transport provider does not allow 
data to be sent with connection establishment functions. 

discon A value greater than or equal to zero specifies the maximum 

amount of data that may be associated with the t_snddis and 
tjcvdis functions; a value of -1 specifies that there is no limit on 
the amount of data sent with these abortive release functions; 
and a value of -2 specifies that the transport provider does not 
allow data to be sent with the abortive release functions. 

servtype This field specifies the service type supported by the transport 

provider, as described below. 

If a transport user is concerned with protocol independence, the above sizes may 
be accessed to determine how large the buffers must be to hold each piece of 
information. Alternatively, the t_alloc function may be used to allocate these 
buffers. An error will result if a transport user exceeds the allowed data size on 
any function. The value of each field may change as a result of option negotia- 
tion, and tjgetinfo enables a user to retrieve the current characteristics. 

The servtype field of info may specify one of the following values on return: 

T COTS The transport provider supports a connection-mode service but 

does not support the optional orderly release facility. 

T_COTS_ORD The transport provider supports a connection-mode service with 
the optional orderly release facility. 

T CLTS The transport provider supports a connectionless-mode service. 

For this service type, t_open will return -2 for etsdu, connect, 
and discon. 

On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport end- 

point. 

[TSYSERR] A system error has occurred during execution of this function. 

SEE ALSO 

t_open(3N). 

Network Programmer's Guide. 
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DIAGNOSTICS 

t_getinfo returns 0 on success and -1 on failure and t_errno is set to indicate the 
error. 
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NAME 

t_getstate — get the current state 
SYNOPSIS 

#include <tiuser.h> 

int tjjetstatetfd) 
int fd; 

DESCRIPTION 

The t_getstate function returns the current state of the provider associated with 
the transport endpoint specified by fd. 

On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint. 

[TSTATECHNG] The transport provider is undergoing a state change. 

[TSYSERR] A system error has occurred during execution of this func- 

tion. 



SEE ALSO 

t_open(3N). 

Network Programmer's Guide. 



DIAGNOSTICS 

t_getstate returns the current state on successful completion and -1 on failure and 
t_errno is set to indicate the error. The current state may be one of the fol- 
lowing: 



TUNBND 

TIDLE 

TOUTCON 

TINCON 

TDATAXFER 

TOUTREL 



unbound 

idle 

outgoing connection pending 
incoming connection pending 
data transfer 

outgoing orderly release (waiting for an orderly release indica- 
tion) 



TINREL 



incoming orderly release (waiting for an orderly release request) 



If the provider is undergoing a state transition when t_getstate is called, the func- 
tion will fail. 
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NAME 

tjisten — listen for a connect request 
SYNOPSIS 

#include <tiuser.h> 

int t listened, call) 
int fd; 

struct t call *call; 

DESCRIPTION 

This function listens for a connect request from a calling transport user. Fd 
identifies the local transport endpoint where connect indications arrive, and on 
return, call contains information describing the connect indication. Call points to 
a t_call structure which contains the following members: 

struct netbuf addr; 
struct netbuf opt; 
struct netbuf udata; 
int sequence; 

Netbuf is described in intro(3). In call, addr returns the protocol address of the 
calling transport user, opt returns protocol-specific parameters associated with 
the connect request, udata returns any user data sent by the caller on the con- 
nect request, and sequence is a number that uniquely identifies the returned con- 
nect indication. The value of sequence enables the user to listen for multiple 
connect indications before responding to any of them. 

Since this function returns values for the addr, opt, and udata fields of call, the 
maxlen [see netbuf in intro( 3)] field of each must be set before issuing the tjisten 
to indicate the maximum size of the buffer for each. 

By default, tjisten executes in synchronous mode and waits for a connect indi- 
cation to arrive before returning to the user. However, if ONDELAY is set (via 
t_open or fcntl), tjisten executes asynchronously, reducing to a poll for existing 
connect indications. If none are available, it returns -1 and sets t_errno to 
TNODATA. 

On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint. 

[TBUFOVFLW] The number of bytes allocated for an incoming argument 

is not sufficient to store the value of that argument. The 
provider's state, as seen by the user, changes to T INCON, 
and the connect indication information to be returned in 
call is discarded. 

0_NDELAY was set, but no connect indications had been 
queued. 

An asynchronous event has occurred on this transport 
endpoint and requires immediate attention. 



[TNODATA] 

[TLOOK] 
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[TNOTSUPPORT] This function is not supported by the underlying transport 
provider. 

[TSYSERR] A system error has occurred during execution of this func- 

tion. 

CAVEATS 

If a user issues tjisten in synchronous mode on a transport endpoint that was 
not bound for listening (i.e. qlen was zero on tj)ind), the call will wait forever 
because no connect indications will arrive on that endpoint. 

SEE ALSO 

intro(3), t_accept(3N), t_bind(3N), t_connect(3N), t_open(3N), t_rcvconnect(3N). 
Network Programmer's Guide. 

DIAGNOSTICS 

tjisten returns 0 on success and -1 on failure and t_errno is set to indicate the 
error. 
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NAME 

t_look — look at the current event on a transport endpoint 
SYNOPSIS 

#include <tiuser.h> 

int t Jook(fd) 
int fd; 

DESCRIPTION 

This function returns the current event on the transport endpoint specified by fd. 
This function enables a transport provider to notify a transport user of an asyn- 
chronous event when the user is issuing functions in synchronous mode. Cer- 
tain events require immediate notification of the user and are indicated by a 
specific error, TLOOK, on the current or next function to be executed. 

This function also enables a transport user to poll a transport endpoint periodi- 
cally for asynchronous events. 

On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport end- 

point. 

[TSYSERR] A system error has occurred during execution of this function. 

SEE ALSO 

t_open(3N). 

Network Programmer's Guide. 

DIAGNOSTICS 

Upon success, tjook returns a value that indicates which of the allowable events 
has occurred, or returns zero if no event exists. One of the following events is 
returned: 

T LISTEN connection indication received 

T_CONNECT connect confirmation received 

T DATA normal data received 

T EXDATA expedited data received 

T DISCONNECT disconnect received 

T ERROR fatal error indication 

T UDERR datagram error indication 

T ORDREL orderly release indication 

On failure, -1 is returned and t_errno is set to indicate the error. 
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NAME 

t open — establish a transport endpoint 
SYNOPSIS 

#include <tiuser.h> 



int t open(path, oflag, info) 
char *path; 
int oflag; 

struct t info *info; 

DESCRIPTION 

t_open must be called as the first step in the initialization of a transport end- 
point. This function establishes a transport endpoint by opening a UNIX file that 
identifies a particular transport provider (i.e. transport protocol) and returning a 
file descriptor that identifies that endpoint. For example, opening the file 
/dev /iso_cots identifies an OSI connection-oriented transport layer protocol as the 
transport provider. 

Path points to the path name of the file to open, and oflag identifies any open 
flags [as in open( 2)]. tjopen returns a file descriptor that will be used by all sub- 
sequent functions to identify the particular local transport endpoint. 

This function also returns various default characteristics of the underlying tran- 
sport protocol by setting fields in the tjnfo structure. This argument points to a 
tjnfo which contains the following members: 



long addr; 
long options; 
long tsdu; 
long etsdu; 

long connect- 

long discon; 

long servtype; 



/* max size of the transport protocol address */ 

/* max number of bytes of protocol-specific options */ 
/* max size of a transport service data unit (TSDU) */ 
/* max size of an expedited transport service 
data unit (ETSDU) */ 

/* max amount of data allowed on connection 
establishment functions */ 

/* max amount of data allowed on t_snddis 
and tjcvdis functions */ 

/* service type supported by the transport provider */ 



The values of the fields have the following meanings: 

addr A value greater than or equal to zero indicates the maximum size 

of a transport protocol address; a value of -1 specifies that there 
is no limit on the address size; and a value of -2 specifies that 
the transport provider does not provide user access to transport 
protocol addresses. 

options A value greater than or equal to zero indicates the maximum 

number of bytes of protocol-specific options supported by the 
provider; a value of -1 specifies that there is no limit on the 
option size; and a value of -2 specifies that the transport provider 
does not support user-settable options. 

tsdu A value greater than zero specifies the maximum size of a tran- 

sport service data unit (TSDU); a value of zero specifies that the 
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transport provider does not support the concept of TSDU, 
although it does support the sending of a data stream with no 
logical boundaries preserved across a connection; a value of -1 
specifies that there is no limit on the size of a TSDU; and a value 
of -2 specifies that the transfer of normal data is not supported 
by the transport provider. 

A value greater than zero specifies the maximum size of an 
expedited transport service data unit (ETSDU); a value of zero 
specifies that the transport provider does not support the concept 
of ETSDU, although it does support the sending of an expedited 
data stream with no logical boundaries preserved across a con- 
nection; a value of -1 specifies that there is no limit on the size 
of an ETSDU; and a value of -2 specifies that the transfer of 
expedited data is not supported by the transport provider. 

A value greater than or equal to zero specifies the maximum 
amount of data that may be associated with connection establish- 
ment functions; a value of -1 specifies that there is no limit on 
the amount of data sent during connection establishment; and a 
value of -2 specifies that the transport provider does not allow 
data to be sent with connection establishment functions. 

discon A value greater than or equal to zero specifies the maximum 

amount of data that may be associated with the tjnddis and 
t_rcvdis functions; a value of -1 specifies that there is no limit on 
the amount of data sent with these abortive release functions; 
and a value of -2 specifies that the transport provider does not 
allow data to be sent with the abortive release functions. 

servtype This field specifies the service type supported by the transport 

provider, as described below. 

If a transport user is concerned with protocol independence, the above sizes may 
be accessed to determine how large the buffers must be to hold each piece of 
information. Alternatively, the t_alloc function may be used to allocate these 
buffers. An error will result if a transport user exceeds the allowed data size on 
any function. 

The servtype field of info may specify one of the following values on return: 

T COTS The transport provider supports a connection-mode service but 

does not support the optional orderly release facility. 

T_COTS_ORD The transport provider supports a connection-mode service with 
the optional orderly release facility. 

T_CLTS The transport provider supports a connectionless-mode service. 

For this service type, t_open will return -2 for etsdu, connect, and 
discon. 

A single transport endpoint may support only one of the above services at one 
time. 



etsdu 



connect 
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If info is set to NULL by the transport user, no protocol information is returned 
by t_open . 

On failure, t_errno may be set to the following: 

[TSYSERR] A system error has occurred during execution of this func- 

tion. 

SEE ALSO 

open(2). 

Network Programmer's Guide. 

DIAGNOSTICS 

t_open returns a valid file descriptor on success and -1 on failure and t_errno is 
set to indicate the error. 
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NAME 

t optmgmt — manage options for a transport endpoint 
SYNOPSIS 

#include <tiuser.h> 

int t optmgmt(fd, req, ret) 
int fd; 

struct t optmgmt *req; 
struct t optmgmt *ret; 

DESCRIPTION 

The t_optmgmt function enables a transport user to retrieve, verify, or negotiate 
protocol options with the transport provider. Fd identifies a bound transport 
endpoint. 

The req and ret arguments point to a t_optmgmt structure containing the fol- 
lowing members: 

struct netbuf opt; 
long flags; 

The opt field identifies protocol options and the flags field is used to specify the 
action to take with those options. 

The options are represented by a netbuf [see intro( 3); also for len , buf and maxlen] 
structure in a manner similar to the address in t_bind. Req is used to request a 
specific action of the provider and to send options to the provider. Len specifies 
the number of bytes in the options, buf points to the options buffer, and maxlen 
has no meaning for the req argument. The transport provider may return 
options and flag values to the user through ret. For ret, maxlen specifies the 
maximum size of the options buffer and buf points to the buffer where the 
options are to be placed. On return, len specifies the number of bytes of options 
returned. Maxlen has no meaning for the req argument, but must be set in the 
ret argument to specify the maximum number of bytes the options buffer can 
hold. The actual structure and content of the options is imposed by the tran- 
sport provider. 

The flags field of req can specify one of the following actions: 

TJMEGOTIATE This action enables the user to negotiate the values of the 
options specified in req with the transport provider. The pro- 
vider will evaluate the requested options and negotiate the 
values, returning the negotiated values through ret. 

TCHECK This action enables the user to verify whether the options 

specified in req are supported by the transport provider. On 
return, the flags field of ret will have either T SUCCESS or 
T FAILURE set to indicate to the user whether the options are 
supported. These flags are only meaningful for the T CHECK 
request. 
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TDEFAULT This action enables a user to retrieve the default options sup- 
ported by the transport provider into the opt field of ret. In req, 
the len field of opt must be zero and the buf field may be NULL. 

If issued as part of the connectionless- mode service, t_optmgmt may block due to 
flow control constraints. The function will not complete until the transport pro- 
vider has processed all previously sent data units. 

On failure, tjerrno may be set to one of the following: 



[TBADF] 

[TOUTSTATE] 

[TACCES] 

[TBADOPT] 

[TBADFLAG] 

[TBUFOVFLW] 



The specified file descriptor does not refer to a transport 
endpoint. 

The function was issued in the wrong sequence. 

The user does not have permission to negotiate the 
specified options. 

The specified protocol options were in an incorrect format 
or contained illegal information. 

An invalid flag was specified. 

The number of bytes allowed for an incoming argument is 
not sufficient to store the value of that argument. The 
information to be returned in ret will be discarded. 



[TSYSERR] 



A system error has occurred during execution of this func- 
tion. 



SEE ALSO 

intro(3), t_ j getinfo(3N), t_open(3N). 

Network Programmer's Guide. 

DIAGNOSTICS 

t_optmgmt returns 0 on success and -1 on failure and t_errno is set to indicate the 
error. 
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NAME 

t rcv — receive data or expedited data sent over a connection 
SYNOPSIS 

int t_rcv(fd, buf, nbytes, flags) 
int fd; 
char *buf; 
unsigned nbytes; 
int *flags; 

DESCRIPTION 

This function receives either normal or expedited data. Fd identifies the local 
transport endpoint through which data will arrive, buf points to a receive buffer 
where user data will be placed, and nbytes specifies the size of the receive buffer. 
Flags may be set on return from tjcv and specifies optional flags as described 
below. 

By default, tjcv operates in synchronous mode and will wait for data to arrive if 
none is currently available. However, if 0_NDELAY is set (via t_open or fcntl), 
tjcv will execute in asynchronous mode and will fail if no data is available. 
(See TNODATA below.) 

On return from the call, if T_MORE is set in flags this indicates that there is more 
data and the current transport service data unit (TSDU) or expedited transport 
service data unit (ETSDU) must be received in multiple tjcv calls. Each tjcv 
with the T_MORE flag set indicates that another tjcv must follow immediately to 
get more data for the current TSDU. The end of the TSDU is identified by the 
return of a tjcv call with the TMORE flag not set. If the transport provider 
does not support the concept of a TSDU as indicated in the info argument on 
return from t_open or t_getinfo, the T MORE flag is not meaningful and should be 
ignored. 

On return, the data returned is expedited data if TEXPEDITED is set in flags. If 
the number of bytes of expedited data exceeds nbytes, tjcv will set T EXPEDITED 
and T MORE on return from the initial call. Subsequent calls to retrieve the 
remaining ETSDU will not have T EXPEDITED set on return. The end of the 
ETSDU is identified by the return of a tjcv call with the T MORE flag not set. 

If expedited data arrives after part of a TSDU has been retrieved, receipt of the 
remainder of the TSDU will be suspended until the ETSDU has been processed. 
Only after the full ETSDU has been retrieved (T MORE not set) will the 
remainder of the TSDU be available to the user. 



On failure, t_errno may be set to one of the following: 



[TBADF] 

[TNODATA] 

[TLOOK] 

[TNOTSUPPORT] 



The specified file descriptor does not refer to a transport 
endpoint. 

0_NDELAY was set, but no data is currently available from 
the transport provider. 

An asynchronous event has occurred on this transport end- 
point and requires immediate attention. 

This function is not supported by the underlying transport 
provider. 
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[TSYSERR] A system error has occurred during execution of this func- 

tion. 

SEE ALSO 

t_open(3N), t_snd(3N). 

Network Programmer's Guide. 

DIAGNOSTICS 

On successful completion, t_rcv returns the number of bytes received, and it 
returns -1 on failure and t errno is set to indicate the error. 
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NAME 

t__rcvconnect — receive the confirmation from a connect request 
SYNOPSIS 

#include <tiuser.h> 

int t_rcvconnect(fd, call) 
int fd; 

struct t call *call; 

DESCRIPTION 

This function enables a calling transport user to determine the status of a previ- 
ously sent connect request and is used in conjunction with t_connect to establish 
a connection in asynchronous mode. The connection will be established on suc- 
cessful completion of this function. 

Fd identifies the local transport endpoint where communication will be esta- 
blished, and call contains information associated with the newly established con- 
nection. Call points to a t_call structure which contains the following members: 

struct netbuf addr; 
struct netbuf opt; 
struct netbuf udata; 
int sequence; 

Netbuf is described in intro( 3). In call, addr returns the protocol address associ- 
ated with the responding transport endpoint, opt presents any protocol-specific 
information associated with the connection, udata points to optional user data 
that may be returned by the destination transport user during connection estab- 
lishment, and sequence has no meaning for this function. 

The maxlen [see netbuf in intro( 3)] field of each argument must be set before 
issuing this function to indicate the maximum size of the buffer for each. How- 
ever, call may be NULL, in which case no information is given to the user on 
return from tjcvconnect. By default, tjcvconnect executes in synchronous mode 
and waits for the connection to be established before returning. On return, the 
addr, opt, and udata fields reflect values associated with the connection. 

If O NDELAY is set (via t_open or fcntl), tjcvconnect executes in asynchronous 
mode, and reduces to a poll for existing connect confirmations. If none are 
available, tjcvconnect fails and returns immediately without waiting for the con- 
nection to be established. (See TNODATA below.) tjcvconnect must be re-issued 
at a later time to complete the connection establishment phase and retrieve the 
information returned in call. 

On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint. 

[TBUFOVFLW] The number of bytes allocated for an incoming argument 

is not sufficient to store the value of that argument and 
the connect information to be returned in call will be dis- 
carded. The provider's state, as seen by the user, will be 
changed to DATAXFER. 
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[TNODATA] 

[TLOOK] 

[TNOTSUPPORT] 

[TSYSERR] 



O NDELAY was set, but a connect confirmation has not yet 
arrived. 

An asynchronous event has occurred on this transport 
connection and requires immediate attention. 

This function is not supported by the underlying transport 
provider. 

A system error has occurred during execution of this func- 
tion. 



SEE ALSO 

intro(3), t_accept(3N), t_bind(3N), t_connect(3N), t_listen(3N), t_open(3N). 
Network Programmer's Guide. 

DIAGNOSTICS 

tjcvconnect returns 0 on success and -1 on failure and t_errno is set to indicate 
the error. 
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NAME 

t_rcvdis — retrieve information from disconnect 
SYNOPSIS 

#include <tiuser.h> 

trcvdis(fd, discon) 
int fd; 

struct t discon * discon; 

DESCRIPTION 

This function is used to identify the cause of a disconnect, and to retrieve any 
user data sent with the disconnect. Fd identifies the local transport endpoint 
where the connection existed, and discon points to a tjliscon structure containing 
the following members: 

struct netbuf udata; 
int reason; 
int sequence; 

Netbuf is described in intro( 3). Reason specifies the reason for the disconnect 
through a protocol-dependent reason code, udata identifies any user data that 
was sent with the disconnect, and sequence may identify an outstanding connect 
indication with which the disconnect is associated. Sequence is only meaningful 
when tjcvdis is issued by a passive transport user who has executed one or 
more tjisten functions and is processing the resulting connect indications. If a 
disconnect indication occurs, sequence can be used to identify which of the out- 
standing connect indications is associated with the disconnect. 

If a user does not care if there is incoming data and does not need to know the 
value of reason or sequence, discon may be NULL and any user data associated 
with the disconnect will be discarded. However, if a user has retrieved more 
than one outstanding connect indication (via tjisten) and discon is NULL, the 
user will be unable to identify with which connect indication the disconnect is 
associated. 

On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint. 

[TNODIS] No disconnect indication currently exists on the specified 

transport endpoint. 

[TBUFOVFLW] The number of bytes allocated for incoming data is not 

sufficient to store the data. The provider's state, as seen 
by the user, will change to T IDLE, and the disconnect 
indication information to be returned in discon will be dis- 
carded. 

[TNOTSUPPORT] This function is not supported by the underlying transport 
provider. 

[TSYSERR] A system error has occurred during execution of this func- 

tion. 
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SEE ALSO 

intro(3), t_connect(3N), t_listen(3N), t_open(3N), t_snddis(3N). 

Network Programmer's Guide. 

DIAGNOSTICS 

tjcvdis returns 0 on success and -1 on failure and t_errno is set to indicate the 
error. 
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NAME 

t_rcvrel — acknowledge receipt of an orderly release indication 
SYNOPSIS 

#include <tiuser.h> 

trcvrel(fd) 
int fd; 

DESCRIPTION 

This function is used to acknowledge receipt of an orderly release indication. Fd 
identifies the local transport endpoint where the connection exists. After receipt 
of this indication, the user may not attempt to receive more data because such 
an attempt will block forever. However, the user may continue to send data 
over the connection if t_sndrel has not been issued by the user. 

This function is an optional service of the transport provider, and is only sup- 
ported if the transport provider returned service type T_COTS_ORD on t_open or 
t_getinfo . 

On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint. 

[TNOREL] No orderly release indication currently exists on the 

specified transport endpoint. 

[TLOOK] An asynchronous event has occurred on this transport 

endpoint and requires immediate attention. 

[TNOTSUPPORT] This function is not supported by the underlying transport 
provider. 

[TSYSERR] A system error has occurred during execution of this func- 

tion, 

SEE ALSO 

t_open(3N), t_sndrel(3N). 

Network Programmer's Guide. 

DIAGNOSTICS 

t rcvrel returns 0 on success and -1 on failure t errno is set to indicate the error. 
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NAME 

t rcvudata — receive a data unit 
SYNOPSIS 

#include <tiuser.h> 

int t_rcvudata(fd, unitdata, flags) 
int fd; 

struct tunitdata *unitdata; 
int *flags; 

DESCRIPTION 

This function is used in connectionless mode to receive a data unit from another 
transport user. Fd identifies the local transport endpoint through which data will 
be received, unitdata holds information associated with the received data unit, 
and flags is set on return to indicate that the complete data unit was not 
received. Unitdata points to a tjmitdata structure containing the following 
members: 



struct netbuf addr; 
struct netbuf opt; 
struct netbuf udata; 

The maxlen [see netbufm intro(3)] field of addr, opt, and udata must be set before 
issuing this function to indicate the maximum size of the buffer for each. 

On return from this call, addr specifies the protocol address of the sending user, 
opt identifies protocol-specific options that were associated with this data unit, 
and udata specifies the user data that was received. 

By default, tjcvudata operates in synchronous mode and will wait for a data 
unit to arrive if none is currently available. However, if ONDELAY is set (via 
t_open or fcntl), tjcvudata will execute in asynchronous mode and will fail if no 
data units are available. 



If the buffer defined in the udata field of unitdata is not large enough to hold the 
current data unit, the buffer will be filled and TMORE will be set in flags on 
return to indicate that another tjcvudata should be issued to retrieve the rest of 
the data unit. Subsequent tjcvudata call(s) will return zero for the length of the 
address and options until the full data unit has been received. 



On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint. 

[TNODATA] O NDELAY was set, but no data units are currently avail- 

able from the transport provider. 

[TBUFOVFLW] The number of bytes allocated for the incoming protocol 

address or options is not sufficient to store the informa- 
tion. The unit data information to be returned in unitdata 
will be discarded. 



[TLOOK] 



An asynchronous event has occurred on this transport 
endpoint and requires immediate attention. 
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[TNOTSUPPORT] This function is not supported by the underlying transport 
provider. 

[TSYSERR] A system error has occurred during execution of this func- 

tion. 

SEE ALSO 

intro(3), t_rcvuderr(3N), t_sndudata(3N). 

Network Programmer's Guide. 

DIAGNOSTICS 

tjcvudata returns 0 on successful completion and -1 on failure and t_errno is set 
to indicate the error. 
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NAME 

t_rcvuderr — receive a unit data error indication 
SYNOPSIS 

#include <tiuser.h> 

int t_rcvuderr(fd, uderr) 
int fd; 

struct t uderr *uderr; 

DESCRIPTION 

This function is used in connectionless mode to receive information concerning 
an error on a previously sent data unit, and should only be issued following a 
unit data error indication. It informs the transport user that a data unit with a 
specific destination address and protocol options produced an error. Fd identifies 
the local transport endpoint through which the error report will be received, and 
uderr points to a t_uderr structure containing the following members: 
struct netbuf addr; struct netbuf opt; long error; 

Netbuf is described in intro( 3). The maxlen [see netbuf in intro( 3)] field of addr 
and opt must be set before issuing this function to indicate the maximum size of 
the buffer for each. 



On return from this call, the addr structure specifies the destination protocol 
address of the erroneous data unit, the opt structure identifies protocol-specific 
options that were associated with the data unit, and error specifies a protocol- 
dependent error code. 

If the user does not care to identify the data unit that produced an error, uderr 
may be set to NULL and tjcvuderr will simply clear the error indication without 
reporting any information to the user. 

On failure, tjerrno may be set to one of the following: 



[TBADF] 

[TNOUDERR] 

[TBUFOVFLW] 



The specified file descriptor does not refer to a transport 
endpoint. 

No unit data error indication currently exists on the specified 
transport endpoint. 

The number of bytes allocated for the incoming protocol 
address or options is not sufficient to store the information. 
The unit data error information to be returned in uderr will 
be discarded. 



[TNOTSUPPORT] This function is not supported by the underlying transport 
provider. 

[TSYSERR] A system error has occurred during execution of this func- 

tion. 
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SEE ALSO 

intro(3), t_rcvudata(3N), t_sndudata(3N). 

Network Programmer's Guide. 

DIAGNOSTICS 

tjcvuderr returns 0 on successful completion and -1 on failure and t errno is set 
to indicate the error. 
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NAME 

t_snd — send data or expedited data over a connection 
SYNOPSIS 

#include <tiuser.h> 

int t snd(fd, buf, nbytes, flags) 

int fd; 

char *buf; 

unsigned nbytes; 

int flags; 

DESCRIPTION 

This function is used to send either normal or expedited data. Fd identifies the 
local transport endpoint over which data should be sent, buf points to the user 
data, nbytes specifies the number of bytes of user data to be sent, and flags 
specifies any optional flags described below. 

By default, t_snd operates in synchronous mode and may wait if flow control 
restrictions prevent the data from being accepted by the local transport provider 
at the time the call is made. However, if 0_NDELAY is set (via t_open or fcntl), 
t_snd will execute in asynchronous mode, and will fail immediately if there are 
flow control restrictions. 

On successful completion, t_snd returns the number of bytes accepted by the 
transport provider. Normally this will equal the number of bytes specified in 
nbytes. However, if 0_NDELAY is set, it is possible that only part of the data 
will be accepted by the transport provider. In this case, t_snd will set TMORE 
for the data that was sent (see below) and will return a value less than nbytes. If 
nbytes is zero, no data will be passed to the provider and t_snd will return zero. 

If TEXPEDITED is set in flags , the data will be sent as expedited data, and will be 
subject to the interpretations of the transport provider. 

If T MORE is set in flags , or set as described above, an indication is sent to the 
transport provider that the transport service data unit (TSDU) (or expedited tran- 
sport service data unit - ETSDU) is being sent through multiple t_snd calls. Each 
t_snd with the T MORE flag set indicates that another t_snd will follow with more 
data for the current TSDU. The end of the TSDU (or ETSDU) is identified by a 
t_snd call with the T MORE flag not set. Use of T MORE enables a user to break 
up large logical data units without losing the boundaries of those units at the 
other end of the connection. The flag implies nothing about how the data is 
packaged for transfer below the transport interface. If the transport provider 
does not support the concept of a TSDU as indicated in the info argument on 
return from t_open or t_getinfo, the T MORE flag is not meaningful and should be 
ignored. 

The size of each TSDU or ETSDU must not exceed the limits of the transport pro- 
vider as returned by t_open or t_getinfo. Failure to comply will result in protocol 
error EPROTO. (See TSYSERR below.) 

If t_snd is issued from the T IDLE state, the provider may silently discard the 
data. If t_snd is issued from any state other than T DATAXFER or T_IDLE, the 
provider will generate an EPROTO error. 
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On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint. 

[TFLOW] OjNDELAY was set, but the flow control mechanism 

prevented the transport provider from accepting data at 
this time. 

[TNOTSUPPORT] This function is not supported by the underlying transport 
provider. 

[TSYSERR] A system error has occurred during execution of this func- 

tion. 

SEE ALSO 

t_open(3N), t_rcv(3N). 

Network Programmer's Guide. 

DIAGNOSTICS 

On successful completion, t_snd returns the number of bytes accepted by the 

transport provider, and it returns -1 on failure and t_errno is set to indicate the 

error. 
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NAME 

t_snddis — send user-initiated disconnect request 
SYNOPSIS 

#include <tiuser.h> 

int t_snddis(fd, call) 
int fd; 

struct t call *call; 

DESCRIPTION 

This function is used to initiate an abortive release on an already established 
connection or to reject a connect request. Fd identifies the local transport end- 
point of the connection, and call specifies information associated with the abor- 
tive release. Call points to a t_call structure which contains the following 
members: 



struct netbuf addr; 
struct netbuf opt; 
struct netbuf udata; 
int sequence; 

Netbuf is described in intro( 3). The values in call have different semantics, 
depending on the context of the call to t_snddis. When rejecting a connect 
request, call must be non-NULL and contain a valid value of sequence to 
uniquely identify the rejected connect indication to the transport provider. The 
addr and opt fields of call are ignored. In all other cases, call need only be used 
when data is being sent with the disconnect request. The addr, opt, and 
sequence fields of the t_call structure are ignored. If the user does not wish to 
send data to the remote user, the value of call may be NULL. 

Udata specifies the user data to be sent to the remote user. The amount of user 
data must not exceed the limits supported by the transport provider as returned 
by t_open or t_getinfo. If the len field of udata is zero, no data will be sent to the 
remote user. 



On failure, t_errno may be set to one of the following: 



[TBADF] 

[TOUTSTATE] 

[TB ADD AT A] 



The specified file descriptor does not refer to a transport 
endpoint. 

The function was issued in the wrong sequence. The tran- 
sport provider's outgoing queue may be flushed, so data 
may be lost. 

The amount of user data specified was not within the 
bounds allowed by the transport provider. The transport 
provider's outgoing queue will be flushed, so data may be 
lost. 



[TBADSEQ] An invalid sequence number was specified, or a NULL call 

structure was specified when rejecting a connect request. 
The transport provider's outgoing queue will be flushed, so 
data may be lost. 
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[TLOOK] An asynchronous event has occurred on this transport end- 

point and requires immediate attention. 

[TNOTSUPPORT] This function is not supported by the underlying transport 
provider. 

[TSYSERR] A system error has occurred during execution of this func- 

tion. 

SEE ALSO 

intro(3), t_connect(3N), t_getinfo(3N), t_listen(3N), t_open(3N). 

Network Programmer's Guide. 

DIAGNOSTICS 

t_snddis returns 0 on success and -1 on failure and t_errno is set to indicate the 

error. 



408 




T_SNDREL(3N) (Networking Support Utilities) T_SNDREL(3N) 

NAME 

tjsndrel — initiate an orderly release 
SYNOPSIS 

#include <tiuser.h> 

int t sndrel(fd) 
int fd; 

DESCRIPTION 

This function is used to initiate an orderly release of a transport connection and 
indicates to the transport provider that the transport user has no more data to 
send. Fd identifies the local transport endpoint where the connection exists. 
After issuing t_sndrel, the user may not send any more data over the connection. 
However, a user may continue to receive data if an orderly release indication has 
been received. 

This function is an optional service of the transport provider, and is only sup- 
ported if the transport provider returned service type T_COTS_ORD on t_open or 
tjgetinfo . 

On failure, t errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint. 

[TFLOW] O NDELAY was set, but the flow control mechanism 

prevented the transport provider from accepting the func- 
tion at this time. 

[TNOTSUPPORT] This function is not supported by the underlying transport 
provider. 

[TSYSERR] A system error has occurred during execution of this func- 

tion. 

SEE ALSO 

t_open(3N), t_rcvrel(3N). 

Network Programmer's Guide. 

DIAGNOSTICS 

tjndrel returns 0 on success and -1 on failure and t_errno is set to indicate the 
error. 
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NAME 

t_sndudata — send a data unit 
SYNOPSIS 

#include <tiuser.h> 

int t_sndudata(fd, unitdata) 
int fd; 

struct t unitdata *unitdata; 

DESCRIPTION 

This function is used in connectionless mode to send a data unit to another tran- 
sport user. Fd identifies the local transport endpoint through which data will be 
sent, and unitdata points to a tjmitdata structure containing the following 
members: 

struct netbuf addr; 
struct netbuf opt; 
struct netbuf udata; 

Netbuf is described in intro( 3). In unitdata , addr specifies the protocol address of 
the destination user, opt identifies protocol-specific options that the user wants 
associated with this request, and udata specifies the user data to be sent. The 
user may choose not to specify what protocol options are associated with the 
transfer by setting the ten field of opt to zero. In this case, the provider may use 
default options. 

If the len field of udata is zero, no data unit will be passed to the transport pro- 
vider; t_sndudata will not send zero-length data units. 

By default, t_sndudata operates in synchronous mode and may wait if flow con- 
trol restrictions prevent the data from being accepted by the local transport pro- 
vider at the time the call is made. However, if 0_NDELAY is set (via t_open or 
fcntl), t_sndudata will execute in asynchronous mode and will fail under such 
conditions. 

If tjndudata is issued from an invalid state, or if the amount of data specified in 
udata exceeds the TSDU size as returned by t_open or t_getinfo, the provider will 
generate an EPROTO protocol error. (See TSYSERR below.) 

On failure, t_errno may be set to one of the following: 

[TBADF] The specified file descriptor does not refer to a transport 

endpoint. 

[TFLOW] 0_NDELAY was set, but the flow control mechanism 

prevented the transport provider from accepting data at this 
time. 

[TNOTSUPPORT] This function is not supported by the underlying transport 
provider. 

[TSYSERR] A system error has occurred during execution of this func- 

tion. 
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SEE ALSO 

intro(3), t_rcvudata(3N), t_rcvuderr(3N). 

Network Programmer's Guide. 

DIAGNOSTICS 

t_sndudata returns 0 on successful completion and -1 on failure t_errno is set to 
indicate the error. 
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NAME 

t_sync — synchronize transport library 
SYNOPSIS 

#include <tiuser.h> 

int t sync(fd) 
int fd; 

DESCRIPTION 

For the transport endpoint specified by fd, t_sync synchronizes the data struc- 
tures managed by the transport library with information from the underlying 
transport provider. In doing so, it can convert a raw file descriptor [obtained via 
open( 2), dup( 2), or as a result of a fork( 2) and exec(2)\ to an initialized transport 
endpoint, assuming that file descriptor referenced a transport provider. This 
function also allows two cooperating processes to synchronize their interaction 
with a transport provider. 

For example, if a process forks a new process and issues an exec, the new process 
must issue a tjync to build the private library data structure associated with a 
transport endpoint and to synchronize the data structure with the relevant pro- 
vider information. 

It is important to remember that the transport provider treats all users of a tran- 
sport endpoint as a single user. If multiple processes are using the same end- 
point, they should coordinate their activities so as not to violate the state of the 
provider. t_sync returns the current state of the provider to the user, thereby 
enabling the user to verify the state before taking further action. This coordina- 
tion is only valid among cooperating processes; it is possible that a process or an 
incoming event could change the provider's state after a tjync is issued. 

If the provider is undergoing a state transition when tjync is called, the function 
will fail. 

On failure, tjrrno may be set to one of the following: 

[TBADF] The specified file descriptor is a valid open file descriptor 

but does not refer to a transport endpoint. 

[TSTATECHNG] The transport provider is undergoing a state change. 

[TSYSERR] A system error has occurred during execution of this func- 

tion. 

SEE ALSO 

dup(2), exec(2), fork(2), open(2). 

Network Programmer's Guide. 

DIAGNOSTICS 

tjync returns the state of the transport provider on successful completion and -1 
on failure and tjrrno is set to indicate the error. The state returned may be one 
of the following: 

TUNBND unbound 

T IDLE idle 
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TOUTCON 

TINCON 

TDATAXFER 

TOUTREL 

T INREL 



outgoing connection pending 
incoming connection pending 
data transfer 

outgoing orderly release (waiting for an orderly release 
indication) 

incoming orderly release (waiting for an orderly release 
request) 
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NAME 

t_unbind — disable a transport endpoint 
SYNOPSIS 

#include <tiuser.h> 

int tunbind(fd) 
int fd; 

DESCRIPTION 

The tjinbind function disables the transport endpoint specified by fd which was 
previously bound by tbind (3N). On completion of this call, no further data or 
events destined for this transport endpoint will be accepted by the transport pro- 
vider. 



On failure, t_errno may be set to one of the following: 



[TBADF] 

[TOUTSTATE] 
[TLOOK] 
[TSYSERR] 
SEE ALSO 



The specified file descriptor does not refer to a transport end- 
point. 

The function was issued in the wrong sequence. 

An asynchronous event has occurred on this transport endpoint. 
A system error has occurred during execution of this function. 



t_bind(3N). 

Network Programmer's Guide. 



DIAGNOSTICS 

t_unbind returns 0 on success and -1 on failure and t_errno is set to indicate the 
error. 
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NAME 

assert — verify program assertion 
SYNOPSIS 

#include <assert.h> 

assert (expression) 
int expression; 

DESCRIPTION 

This macro is useful for putting diagnostics into programs. When it is executed, 
if expression is false (zero), assert prints 

"Assertion failed: expression, file xyz, line nnn" 

on the standard error output and aborts. In the error message, xyz is the name 
of the source file and nnn the source line number of the assert statement. 

Compiling with the preprocessor option -DNDEBUG [see cpp( 1)], or with the 
preprocessor control statement "#defme NDEBUG" ahead of the "#include 
<assert.h>" statement, will stop assertions from being compiled into the pro- 
gram. 

SEE ALSO 

cpp(l), abort(3C). 

CAVEAT 

Since assert is implemented as a macro, the expression may not contain any 
string literals. 
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NAME 

crypt — password and file encryption functions 
SYNOPSIS 

cc [flag ...] file ... -lcrypt 

char *crypt (key, salt) 
char *key, *salt; 

void setkey (key) 
char *key; 

void encrypt (block, flag) 
char *block; 
int flag; 

char *des_crypt (key, salt) 
char *key, *salt; 

void des setkey (key) 
char *key; 

void des encrypt (block, flag) 
char *block; 
int flag; 

int run setkey (p, key) 
int p[2]; 
char *key; 

int run crypt (offset, buffer, count, p) 

long offset; 

char *buffer; 

unsigned int count; 

int p[2]; 

int crypt jclose(p) 
int p[2]; 

DESCRIPTION 

des_crypt is the password encryption function. It is based on a one way hashing 
encryption algorithm with variations intended (among other things) to frustrate 
use of hardware implementations of a key search. 

Key is a user's typed password. Salt is a two-character string chosen from the 
set [a-z A-ZO-9./ ]; this string is used to perturb the hashing algorithm in one of 
4096 different ways, after which the password is used as the key to encrypt 
repeatedly a constant string. The returned value points to the encrypted pass- 
word. The first two characters are the salt itself. 

The des_setkey and des_encrypt entries provide (rather primitive) access to the 
actual hashing algorithm. The argument of des_setkey is a character array of 
length 64 containing only the characters with numerical value 0 and 1. If this 
string is divided into groups of 8, the low-order bit in each group is ignored; this 
gives a 56-bit key which is set into the machine. This is the key that will be 
used with the hashing algorithm to encrypt the string block with the function 
des_encrypt. 
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The argument to the des_encrypt entry is a character array of length 64 con- 
taining only the characters with numerical value 0 and 1. The argument array is 
modified in place to a similar array representing the bits of the argument after 
having been subjected to the hashing algorithm using the key set by des_setkey. 
If edflag is zero, the argument is encrypted; if non-zero, it is decrypted. 

Note that decryption is not provided in the international version of crypt( 3X). 
The international version is part of the C Programming Language Utilities , and 
the domestic version is part of the Security Administration Utilities. If decryp- 
tion is attempted with the international version of des_encrypt, an error message 
is printed. 

Crypt, setkey, and encrypt are front-end routines that invoke des_crypt, 
dessetkey, and des_encrypt respectively. 

The routines run_setkey and run_crypt are designed for use by applications that 
need cryptographic capabilities [such as ed( 1) and vi( 1)] that must be compatible 
with the crypt( 1) user-level utility. Run_setkey establishes a two-way pipe con- 
nection with crypt( 1), using key as the password argument. Run_crypt takes a 
block of characters and transforms the cleartext or ciphertext into their ciphertext 
or cleartext using crypt( 1). Offset is the relative byte position from the beginning 
of the file that the block of text provided in block is coming from. Count is the 
number of characters in block, and connection is an array containing indices to a 
table of input and output file streams. When encryption is finished, crypt _close is 
used to terminate the connection with crypt( 1). 

Run_setkey returns -1 if a connection with crypt( 1) cannot be established. This 
will occur on international versions of UNIX where crypt( 1) is not available. If a 
null key is passed to runjetkey, 0 is returned. Otherwise, 1 is returned. 
Run_crypt returns -1 if it cannot write output or read input from the pipe 
attached to crypt. Otherwise it returns 0. 

DIAGNOSTICS 

In the international version of crypt( 3X), a flag argument of 1 to des_encrypt is 
not accepted, and an error message is printed. 

SEE ALSO 

getpass(3C), passwd(4). 

crypt(l), login(l), passwd(l) in the User's Reference Manual. 

CAVEAT 

The return value in crypt points to static data that are overwritten by each call. 
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NAME 

curses — terminal screen handling and optimization package 
SYNOPSIS 

The curses manual page is organized as follows: 

In SYNOPSIS 

- compiling information 

- summary of parameters used by curses routines 

- alphabetical list of curses routines, showing their parameters 

In DESCRIPTION: 

- An overview of how curses routines should be used 

In ROUTINES, descriptions of each curses routines, are grouped under the 
appropriate topics: 

- Overall Screen Manipulation 

- Window and Pad Manipulation 

- Output 

- Input 

- Output Options Setting 

- Input Options Setting 

- Environment Queries 

- Soft Labels 

- Low-level Curses Access 

- Terminfo-Level Manipulations 

- Termcap Emulation 

- Miscellaneous 

- Use of curscr 

Then come sections on: 

- ATTRIBUTES 

- FUNCTION CALLS 

- LINE GRAPHICS 



cc [flag ...] file ... — Icurses [library ...] 

#include <curses.h> (automatically includes <stdio.h>, 

<termio.h>, and <unctrl.h>). 

The parameters in the following list are not global variables, but rather this 
is a summary of the parameters used by the curses library routines. All 
routines return the int values ERR or OK unless otherwise noted. Routines 
that return pointers always return NULL on error. (ERR, OK, and NULL are 
all defined in <curses.h>.) Routines that return integers are not listed in 
the parameter list below. 

bool bf 

char **area,*boolnames[], *boolcodes[], *boolfnames[], *bp 
char *cap, *capname, codename[2], erasechar, *filename, *fmt 
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char *keyname, killchar, *label, *longname 
char *name, *numnames[], *numcodes[], *numfnames[] 
char *slk_label, *str, *strnames[], *strcodes[], *strfnames[] 
char *term, *tgetstr, *tigetstr, *tgoto, *tparm, *type 
chtype attrs, ch, horch, vertch 
FILE *infd, *outfd 

int beginx, begin_y, begline, bot, c, col, count 

int dmaxcol, dmaxrow, dmincol, dminrow, *errret, fildes 

int (*init( )), labfmt, labnum, line 

int ms, ncols, new, newcol, newrow, nlines, numlines 
int oldcol, oldrow, overlay 

int pi, p2, p9, pmincol, pminrow, (*putc( )), row 
int smaxcol, smaxrow, smincol, sminrow, start 
int tenths, top, visibility, x, y 
SCREEN *new, *newterm, *set_term 
TERMINAL *cur_term, *nterm, *oterm 
va list varglist 

WINDOW *curscr, *dstwin, *initscr, *newpad, *newwin, *orig 
WINDOW *pad, *srcwin, *stdscr, *subpad, *subwin, *win 

addch(ch) 

addstr(str) 

attroff(attrs) 

attron(attrs) 

attrset(attrs) 

baudrate() 

beep() 

box(win, vertch, horch) 

cbreak( ) 
clear( ) 

clearok(win, bf) 
clrtobot( ) 
clrtoeol( ) 

copywin(srcwin, dstwin, sminrow, smincol, dminrow, dmincol, 
dmaxrow, dmaxcol, overlay)" 
curs_set( visibility) 
def _prog mode( ) 
def shell_mode( ) 
delcurterm(oterm) 
delay output(ms) 
delch() 
deleteln( ) 
delwin(win) 
doupdateQ 
draino(ms) 
echo() 

echochar(ch) 
endwin( ) 
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eraseQ 
erasechar( ) 
filterO 
flashQ 
flushinp( ) 

garbagedlines(win, begline, numlines) 

getbegyx(win, y, x) 

getch() 

getmaxyx(win, y, x) 
getstr(str) 
getsyx(y, x) 
getyx(win, y; x) 
halfdelay(tenths) 
has_ic( ) 
hasilQ 
idlok(win, bf) 
inch() 
initscr( ) 
insch(ch) 
insertln( ) 
intrflush(win, bf) 
isendwin( ) 
keyname(c) 
keypad(win, bf) 
killchar( ) 
leaveok(win, bf) 
longname( ) 
meta(win, bf) 
move(y, x) 
mvaddch(y, x, ch) 
mvaddstr(y, x, str) 

mvcur(oldrow, oldcol, newrow, newcol) 

mvdelch(y, x) 

mvgetch(y, x) 

mvgetstr(y, x, str) 

mvinch(y, x) 

mvinsch(y, x, ch) 

mvprintw(y / x, fmt [, arg...]) 

mvscanw(y, x, fmt [, arg...]) 

mvwaddch(win, y, x, ch) 

mvwaddstr(win, y, x, str) 

mvwdelch(win, y, x) 

mvwgetch(win, y, x) 

mvwgetstr(win, y, x, str) 

mvwin(win, y, x) 

mvwinch(win, y, x) 

mvwinsch(win, y, x, ch) 

mvwprintw(win, y, x, fmt [, arg...]) 

mvwscanw(win, y, x, fmt [, arg...]) 
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napms(ms) 

newpad(nlines, ncols) 
newterm(type, outfd, infd) 
newwin(nlines, ncols, begin_y, begin_x) 

nl() 

nocbreak( ) 
nodelay(win, bf) 
noecho( ) 
nonl() 
noraw( ) 

notimeout(win, bf) 
overlay(srcwin, dstwin) 
overwrite(srcwin, dstwin) 
pechochar(pad, ch) 

pnoutrefresh(pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol) 

prefresh(pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol) 

printw(fmt [, arg...]) 

putp(str) 

raw() 

refresh( ) 

reset_prog_mode( ) 
reset_shell_mode( ) 
resetty() 

restartterm(term, fildes, errret) 
ripoffline(line, init) 
savetty ( ) 

scanw(fmt [, arg...]) 

scrdump(filename) 

scr_init(filename) 

scr_restore(filename) 

scroll(win) 

scrollok(win, bf) 

set_curterm(nterm) 

set_term(new) 

setscrreg(top, bot) 

setsyx(y, x) 

setupterm(term, fildes, errret) 

slk_clear( ) 

slk_init(fmt) 

slk_label(labnum) 

slk noutrefresh( ) 

slk_refresh( ) 

slk restore( ) 

slk_set(labnum, label, fmt) 
slk_touch( ) 
standend() 
standout( ) 

subpad(orig, nlines, ncols, begin_y, begin_x) 
subwin(orig, nlines, ncols, begin_y, begin_x) 
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tgetent(bp, name) 

tgetflag(codename) 

tgetnum(codename) 

tgetstr(codename, area) 

tgoto(cap, col, row) 

tigetflag(capname) 

tigetnum(capname) 

tigetstr(capname) 

touchIine(win / start, count) 

touchwin(win) 

tparm(str, pi, p2, ..., p9) 

tputs(str, count, putc) 

traceoff( ) 

traceon( ) 

typeahead(fildes) 

unctrl(c) 

ungetch(c) 

vidattr(attrs) 

vidputs(attrs, putc) 

vwprintw(win, fmt, varglist) 

vwscanw(win, fmt, varglist) 

waddch(win, ch) 

waddstr(win, str) 

wattroff(win, attrs) 

wattron(win, attrs) 

wattrset(win, attrs) 

wclear(win) 

wclrtobot(win) 

wclrtoeol(win) 

wdelch(win) 

wdeleteln(win) 

wechochar(win, ch) 

werase(win) 

wgetch(win) 

wgetstr(win, str) 

winch(win) 

winsch(win, ch) 

winsertln(win) 

wmove(win, y, x) 

wnoutrefresh(win) 

wprintw(win, fmt [, arg...]) 

wrefresh(win) 

wscanw(win, fmt [, arg...]) 

wsetscrreg(win, top, hot) 

wstandend(win) 

wstandout(win) 

DESCRIPTION 

The curses routines give the user a terminal-independent method of updating 
screens with reasonable optimization. 
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In order to initialize the routines, the routine initscr() or newtermQ must be 
called before any of the other routines that deal with windows and screens are 
used. (Three exceptions are noted where they apply.) The routine endwinQ 
must be called before exiting. To get character-at-a-time input without echoing, 
(most interactive, screen oriented programs want this) after calling initscrQ you 
should call "cbreakQ; noechoQ;" Most programs would additionally call 
"nonlQ; intrflush (stdscr, FALSE); keypad(stdscr, TRUE);". 

Before a curses program is run, a terminal's tab stops should be set and its ini- 
tialization strings, if defined, must be output. This can be done by executing the 
tput init command after the shell environment variable TERM has been 
exported. For further details, see profile^), tput( 1), and the "Tabs and Initializa- 
tion" subsection of terminfo( 4). 

The curses library contains routines that manipulate data structures called win- 
dows that can be thought of as two-dimensional arrays of characters representing 
all or part of a terminal screen. A default window called stdscr is supplied, 
which is the size of the terminal screen. Others may be created with newwin(). 
Windows are referred to by variables declared as WINDOW *; the type WINDOW 
is defined in <curses.h> to be a C structure. These data structures are manipu- 
lated with routines described below, among which the most basic are move() 
and addchQ. (More general versions of these routines are included with names 
beginning with w, allowing you to specify a window. The routines not begin- 
ning with w usually affect stdscr.) Then refreshQ is called, telling the routines 
to make the user's terminal screen look like stdscr. The characters in a window 
are actually of type chtype, so that other information about the character may 
also be stored with each character. 

Special windows called pads may also be manipulated. These are windows 
which are not constrained to the size of the screen and whose contents need not 
be displayed completely. See the description of newpad( ) under "Window and 
Pad Manipulation" for more information. 

In addition to drawing characters on the screen, video attributes may be 
included which cause the characters to show up in modes such as underlined or 
in reverse video on terminals that support such display enhancements. Line 
drawing characters may be specified to be output. On input, curses is also able 
to translate arrow and function keys that transmit escape sequences into single 
values. The video attributes, line drawing characters, and input values use 
names, defined in <curses.h>, such as A REVERSE, ACSHLINE, and KEY LEFT. 

curses also defines the WINDOW * variable, curscr, which is used only for cer- 
tain low-level operations like clearing and redrawing a garbaged screen, curscr 
can be used in only a few routines. If the window argument to clear ok() is 
curscr, the next call to wrefreshQ with any window will cause the screen to be 
cleared and repainted from scratch. If the window argument to wrefreshQ is 
curscr, the screen in immediately cleared and repainted from scratch. This is 
how most programs would implement a "repaint-screen" function. More infor- 
mation on using curscr is provided where its use is appropriate. 

The environment variables LINES and COLUMNS may be set to override ter- 
minfo's idea of how large a screen is. These may be used in an AT&T Teletype 
5620 layer, for example, where the size of a screen is changeable. 
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If the environment variable TERMINFO is defined, any program using curses will 
check for a local terminal definition before checking in the standard place. For 
example, if the environment variable TERM is set to att4425 / then the compiled 
terminal definition is found in / usr/lib /terminfo/ a/ att4425 . (The a is copied 
from the first letter of att4425 to avoid creation of huge directories.) However, if 
TERMINFO is set to $HOME/ my terms, curses will first check 

$HOME/myterms/a/att4425 / and, if that fails, will then check 

/usr/lib/terminfo/a/att4425. This is useful for developing experimental 
definitions or when write permission on /usr /lib /terminfo is not available. 

The integer variables LINES and COLS are defined in <curses.h>, and will be 
filled in by initscr( ) with the size of the screen. (For more information, see the 
subsection "Terminfo-Level Manipulations".) The constants TRUE and FALSE 
have the values 1 and 0, respectively. The constants ERR and OK are returned 
by routines to indicate whether the routine successfully completed. These con- 
stants are also defined in <curses.h>. 

ROUTINES 

Many of the following routines have two or more versions. The routines 
prefixed with w require a window argument. The routines prefixed with p 
require a pad argument. Those without a prefix generally use stdscr. 

The routines prefixed with mv require y and x coordinates to move to before 
performing the appropriate action. The mv() routines imply a call to moveQ 
before the call to the other routine. The window argument is always specified 
before the coordinates, y always refers to the row (of the window), and x 
always refers to the column. The upper left corner is always (0,0), not (1,1). 
The routines prefixed with mvw take both a window argument and y and x coor- 
dinates. 

In each case, win is the window affected and pad is the pad affected, (win and 
pad are always of type WINDOW *.) Option-setting routines require a boolean 
flag bf with the value TRUE or FALSE. ( bf is always of type bool.) The types 

WINDOW, bool, and chtype are defined in <curses.h>. See the SYNOPSIS for 

a summary of what types all variables are. 

All routines return either the integer ERR or the integer OK, unless otherwise 
noted. Routines that return pointers always return NULL on error. 

Overall Screen Manipulation 

WINDOW *initscr() The first routine called should almost always be initscr(). 

(The exceptions are slk_init( ), filter( ), and ripofflineQ.) 

This will determine the terminal type and initialize all 

curses data structures. initscrQ also arranges that the first 
call to refreshQ will clear the screen. If errors occur, 
initscrQ will write an appropriate error message to stan- 
dard error and exit; otherwise, a pointer to stdscr is 
returned. If the program wants an indication of error con- 
ditions, newtermQ should be used instead of initscrQ. 
initscr( ) should only be called once per application. 

endwinQ A program should always call endwinQ before exiting or 

escaping from curses mode temporarily, to do a shell 
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escape or system{ 3S) call, for example. This routine will 
restore tty{7) modes, move the cursor to the lower left 
corner of the screen and reset the terminal into the proper 
non- visual mode. To resume after a temporary escape, 
call wrefresh() or doupdateQ. 

isendwin() Returns TRUE if endwinQ has been called without any 

subsequent calls to wrefreshQ. 

SCREEN *newterm(type, outfd, infd) 

A program that outputs to more than one terminal must 
use newterm() for each terminal instead of initscrQ. A 
program that wants an indication of error conditions, so 
that it may continue to run in a line-oriented mode if the 
terminal cannot support a screen-oriented program, must 
also use this routine. newterm() should be called once 
for each terminal. It returns a variable of type SCREEN* 
that should be saved as a reference to that terminal. The 
arguments are the type of the terminal to be used in place 
of the environment variable TERM; outfd, a stdio( 3S) file 
pointer for output to the terminal; and infd, another file 
pointer for input from the terminal. When it is done run- 
ning, the program must also call endwinQ for each ter- 
minal being used. If newtermQ is called more than once 
for the same terminal, the first terminal referred to must 
be the last one for which endwinQ is called. 

SCREEN *set_term(new) 

This routine is used to switch between different terminals. 
The screen reference new becomes the new current ter- 
minal. A pointer to the screen of the previous terminal is 
returned by the routine. This is the only routine which 
manipulates SCREEN pointers; all other routines affect 
only the current terminal. 

Window and Pad Manipulation 

refresh( ) 

wrefresh (win) These routines (or prefreshQ, pnoutrefreshQ, 

wnoutrefreshQ, or doupdateQ) must be called to write 
output to the terminal, as most other routines merely 
manipulate data structures. wrefreshQ copies the named 
window to the physical terminal screen, taking into 
account what is already there in order to minimize the 
amount of information that's sent to the terminal (called 
optimization). refreshQ does the same thing, except it 
uses stdscr as a default window. Unless leaveokQ has 
been enabled, the physical cursor of the terminal is left at 
the location of the window's cursor. The number of char- 
acters output to the terminal is returned. 

Note that refreshQ is a macro. 
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These two routines allow multiple updates to the physical 
terminal screen with more efficiency than wrefreshQ 
alone. How this is accomplished is described in the next 
paragraph. 

curses keeps two data structures representing the terminal 
screen: a physical terminal screen, describing what is actu- 
ally on the screen, and a virtual terminal screen, 
describing what the programmer wants to have on the 
screen. wrefreshQ works by first calling wnoutrefresh( ), 
which copys the named window to the virtual screen, and 
then by calling doupdateQ, which compares the virtual 
screen to the physical screen and does the actual update. 
If the programmer wishes to output several windows at 
once, a series of calls to wrefreshQ will result in alter- 
nating calls to wnoutrefresh( ) and doupdateQ, causing 
several bursts of output to the screen. By first calling 
wnoutrefresh( ) for each window, it is then possible to call 
doupdateQ once, resulting in only one burst of output, 
with probably fewer total characters transmitted and cer- 
tainly less processor time used. 

WINDOW *newwin(nlines, ncols, begin_y, begin_x) 

Create and return a pointer to a new window with the 
given number of lines (or rows), nlines, and columns, 
ncols. The upper left corner of the window is at line 
begin _y, column begin _x. If either nlines or ncols is 0, they 
will be set to the value of lines— begin jy and cols —beginjc. 
A new full-screen window is created by calling 
newwin(0,0,0,0). 

mvwin(win, y, x) Move the window so that the upper left corner will be at 
position (y, x). If the move would cause the window to 
be off the screen, it is an error and the window is not 
moved. 

WINDOW *subwin(orig, nlines, ncols, begin_y, begin_x) 

Create and return a pointer to a new window with the 
given number of lines (or rows), nlines, and columns, 
ncols. The window is at position (beginjy, beginjc) on the 
screen. (This position is relative to the screen, and not to 
the window orig.) The window is made in the middle of 
the window orig, so that changes made to one window 
will affect both windows. When using this routine, often 
it will be necessary to call touch winQ or touchlineQ on 
orig before calling wrefreshQ. 

delwin(win) Delete the named window, freeing up all memory associ- 

ated with it. In the case of overlapping windows, subwin- 
dows should be deleted before the main window. 
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WINDOW *newpad(nlines, ncols) 

Create and return a pointer to a new pad data structure 
with the given number of lines (or rows), nlines, and 
columns, ncols. A pad is a window that is not restricted 
by the screen size and is not necessarily associated with a 
particular part of the screen. Pads can be used when a 
large window is needed, and only a part of the window 
will be on the screen at one time. Automatic refreshes of 
pads (e.g. from scrolling or echoing of input) do not occur. 
It is not legal to call wrefresh() with a pad as an argu- 
ment; the routines pref resh( ) or pnoutrefresh( ) should be 
called instead. Note that these routines require additional 
parameters to specify the part of the pad to be displayed 
and the location on the screen to be used for display. 

WINDOW *subpad(orig, nlines, ncols, begin_y, begin_x) 

Create and return a pointer to a subwindow within a pad 
with the given number of lines (or rows), nlines, and 
columns, ncols. Unlike subwin( ), which uses screen coor- 
dinates, the window is at position (begin jy, begin jc) on the 
pad. The window is made in the middle of the window 
orig, so that changes made to one window will affect both 
windows. When using this routine, often it will be neces- 
sary to call touch win() or touchlineQ on orig before cal- 
ling prefreshQ. 

prefresh(pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol) 

pnoutrefresh(pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol) 

These routines are analogous to wrefreshQ and 
wnoutrefresh( ) except that pads, instead of windows, are 
involved. The additional parameters are needed to indi- 
cate what part of the pad and screen are involved. 
pminrow and pmincol specify the upper left corner, in the 
pad, of the rectangle to be displayed, sminrow, smincol, 
smaxrow, and smaxcol specify the edges, on the screen, of 
the rectangle to be displayed in. The lower right corner in 
the pad of the rectangle to be displayed is calculated from 
the screen coordinates, since the rectangles must be the 
same size. Both rectangles must be entirely contained 
within their respective structures. Negative values of 
pminrow, pmincol, sminrow, or smincol are treated as if 
they were zero. 
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Output 

These routines are used to "draw" text on windows. 

addch(ch) 
waddch(win, ch) 
mvaddch(y, x, ch) 
mvwaddch(win, y, x, ch) 

The character ch is put into the window at the current 
cursor position of the window and the position of the 
window cursor is advanced. Its function is similar to that 
of putchar (see putc( 3'SJ). At the right margin, an 
automatic newline is performed. At the bottom of the 
scrolling region, if scrollokQ is enabled, the scrolling 
region will be scrolled up one line. 

If ch is a tab, newline, or backspace, the cursor will be 
moved appropriately within the window. A newline also 
does a clrtoeolQ before moving. Tabs are considered to 
be at every eighth column. If ch is another control char- 
acter, it will be drawn in the *X notation. (Calling 
winchQ after adding a control character will not return 
the control character, but instead will return the represen- 
tation of the control character.) 

Video attributes can be combined with a character by or- 
ing them into the parameter. This will result in these 
attributes also being set. (The intent here is that text, 
including attributes, can be copied from one place to 
another using inch( ) and addchQ.) See standout(), below. 

Note that ch is actually of type chtype, not a character. 

Note that addch( ), mvaddch( ), and mvwaddchQ, are 
macros. 

echochar(ch) 
wechochar(win, ch) 

pechochar(pad, ch) These routines are functionally equivalent to a call to 
addch(ch) followed by a call to refresh( ), a call to 
waddch(win, ch) followed by a call to wrefresh(win), or a 
call to waddch(pad, ch) followed by a call to 
prefresh(pad). The knowledge that only a single char- 
acter is being output is taken into consideration and, for 
non-control characters, a considerable performance gain 
can be seen by using these routines instead of their 
equivalents. In the case of pechochar(), the last location 
of the pad on the screen is reused for the arguments to 
prefreshQ. 

Note that ch is actually of type chtype, not a character. 
Note that echochar( ) is a macro. 
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addstr(str) 
waddstr(win, str) 
mvwaddstr(win, y, 
mvaddstr(y, x, str) 



attroff(attrs) 
wattroff(win, attrs) 
attron(attrs) 
wattron(win, attrs) 
attrset(attrs) 
wattrset(win, attrs) 
standendQ 
wstandend(win) 
standout( ) 
wstandout(win) 



beep() 

flashQ 



x, str) 

These routines write all the characters of the null- 
terminated character string str on the given window. This 
is equivalent to calling waddch() once for each character 
in the string. 

Note that addstrQ, mvaddstr(), and mvwaddstrQ are 
macros. 



These routines manipulate the current attributes of the 
named window. These attributes can be any combination 
of A ST ANDOUT, AREVERSE, ABOLD, ADIM, ABLINK, 
AUNDERLINE, and A ALT CHARSET . These constants are 
defined in <curses.h> and can be combined with the C 
logical OR ( | ) operator. 

The current attributes of a window are applied to all char- 
acters that are written into the window with waddchQ. 
Attributes are a property of the character, and move with 
the character through any scrolling and insert/delete 
line/character operations. To the extent possible on the 
particular terminal, they will be displayed as the graphic 
rendition of the characters put on the screen. 

attrset(attrs) sets the current attributes of the given 
window to attrs. attroff(attrs) turns off the named attri- 
butes without turning on or off any other attributes. 
attron(attrs) turns on the named attributes without 
affecting any others. standout( ) is the same as 
attron( A STANDOUT). standendQ is the same as attrset 
(0), that is, it turns off all attributes. 

Note that attrs is actually of type chtype, not a character. 

Note that attroffQ, attronQ, attrsetQ, standendQ, and 
standoutQ are macros. 



These routines are used to signal the terminal user. 
beepQ will sound the audible alarm on the terminal, if 
possible, and if not, will flash the screen (visible bell), if 
that is possible. flashQ will flash the screen, and if that is 
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not possible, will sound the audible signal. If neither 
signal is possible, nothing will happen. Nearly all termi- 
nals have an audible signal (bell or beep) but only some 
can flash the screen. 

box(win, vertch, horch) 

A box is drawn around the edge of the window, win. 
vertch and horch are the characters the box is to be drawn 
with. If vertch and horch are 0, then appropriate default 
characters, ACS_VLINE and ACS HLINE, will be used. 

Note that vertch and horch are actually of type chtype, not 
characters. 



erase( ) 
werase(win) 



clear( ) 
wclear(win) 



clrtobot( ) 
wclrtobot(win) 



clrtoeol( ) 
wclrtoeol(win) 



These routines copy blanks to every position in the 
window. 

Note that eraseQ is a macro. 

These routines are like erase( ) and werase( ), but they also 
call clearok(), arranging that the screen will be cleared 
completely on the next call to wrefresh( ) for that window, 
and repainted from scratch. 

Note that clearQ is a macro. 



All lines below the cursor in this window are erased. 
Also, the current line to the right of the cursor, inclusive, 
is erased. 

Note that clrtobotQ is a macro. 



The current line to the right of the cursor, inclusive, is 
erased. 

Note that clrtoeol( ) is a macro. 



delay output(ms) Insert a ms millisecond pause in the output. It is not 
recommended that this routine be used extensively, 
because padding characters are used rather than a pro- 
cessor pause. 

delchQ 
wdelch(win) 
mvdelch(y, x) 

mvwdelch(win, y, x) The character under the cursor in the window is deleted. 

All characters to the right on the same line are moved to 
the left one position and the last character on the line is 
filled with a blank. The cursor position does not change 
(after moving to (y, x), if specified). (This does not imply 
use of the hardware "delete-character" feature.) 
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Note that delch(), mvdelch(), and mvwdelch() are 
macros. 

deleteln( ) 

wdeleteln(win) The line under the cursor in the window is deleted. All 
lines below the current line are moved up one line. The 
bottom line of the window is cleared. The cursor position 
does not change. (This does not imply use of the 
hardware "delete-line" feature.) 

Note that deleteln( ) is a macro. 

getyx(win, y, x) The cursor position of the window is placed in the two 
integer variables y and x. This is implemented as a macro, 
so no is necessary before the variables. 

getbegyx(win, y, x) 

getmaxyx(win, y, x) Like getyx(), these routines store the current beginning 
coordinates and size of the specified window. 

Note that getbegyxQ and getmaxyxQ are macros. 

insch(ch) 
winsch(win, ch) 
mvwinsch(win, y, x, ch) 

mvinsch(y, x, ch) The character ch is inserted before the character under the 
cursor. All characters to the right are moved one space to 
the right, possibly losing the rightmost character of the 
line. The cursor position does not change (after moving to 
(y, x), if specified). (This does not imply use of the 
hardware "insert-character" feature.) 

Note that ch is actually of type chtype, not a character. 

Note that inschQ, mvinsch(), and mvwinsch() are 
macros. 

A blank line is inserted above the current line and the 
bottom line is lost. (This does not imply use of the 
hardware "insert-line" feature.) 

Note that insertln( ) is a macro. 

move(y, x) 

wmove(win, y, x) The cursor associated with the window is moved to line 
(row) y, column x. This does not move the physical 
cursor of the terminal until refreshQ is called. The posi- 
tion specified is relative to the upper left corner of the 
window, which is (0, 0). 

Note that move() is a macro. 

overlay(srcwin, dstwin) 



insertln( ) 
winsertln(win) 
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overwrite(srcwin, dstwin) 

These routines overlay srcwin on top of dstwin; that is, all 
text in srcwin is copied into dstwin. scrwin and dstwin 
need not be the same size; only text where the two win- 
dows overlap is copied. The difference is that overlay( ) is 
non-destructive (blanks are not copied), while overwrite() 
is destructive. 

copywin(srcwin, dstwin, sminrow, smincol, dminrow, dmincol, dmaxrow, 

dmaxcol, overlay) This routine provides a finer grain of control over the 
overlay() and overwrite() routines. Like in the 
prefreshQ routine, a rectangle is specified in the destina- 
tion window, ( dminrow , dmincol) and (dmaxrow, dmaxcol ), 
and the upper-left-corner coordinates of the source 
window, (sminrow, smincol ). If the argument overlay is 
true, then copying is non-destructive, as in overlayQ. 

printw(fmt [, arg...]) 
wprintw(win, fmt [, arg . . .]) 
mvprintw(y, x, fmt [, arg...]) 
mvwprintw(win, y, x, fmt [, arg...]) 

These routines are analogous to printf(3). The string 
which would be output by printf(3) is instead output 
using waddstr( ) on the given window. 

vwprintw(win, fmt, varglist) 

This routine corresponds to vfprintf( 3S). It performs a 
wprintwQ using a variable argument list. The third argu- 
ment is a vajist, a pointer to a list of arguments, as 
defined in <varargs.h>. See the vprintf (3S) and 
varargs(5) manual pages for a detailed description on how 
to use variable argument lists. 

scroll(win) The window is scrolled up one line. This involves moving 

the lines in the window data structure. As an optimiza- 
tion, if the window is stdscr and the scrolling region is the 
entire window, the physical screen will be scrolled at the 
same time. 

touchwin(win) 
touchline(win, start, count) 

Throw away all optimization information about which 
parts of the window have been touched, by pretending 
that the entire window has been drawn on. This is some- 
times necessary when using overlapping windows, since a 
change to one window will affect the other window, but 
the records of which lines have been changed in the other 
window will not reflect the change. touchlineQ only pre- 
tends that count lines have been changed, beginning with 
line start . 
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getch() 
wgetch(win) 
mvgetch(y, x) 

mvwgetch(win, y, x) A character is read from the terminal associated with the 
window. In NODELAY mode, if there is no input waiting, 
the value ERR is returned. In DELAY mode, the program 
will hang until the system passes text through to the pro- 
gram. Depending on the setting of cbreakQ, this will be 
after one character (CBREAK mode), or after the first new- 
line (NOCBREAK mode). In HALF-DELAY mode, the pro- 
gram will hang until a character is typed or the specified 
timeout has been reached. Unless noecho() has been set, 
the character will also be echoed into the designated 
window. No refreshQ will occur between the move() 
and the getchQ done within the routines mvgetch() and 
mvwgetch( ). 

When using getchQ, wgetchQ, mvgetchQ, or 
mvwgetchQ, do not set both NOCBREAK mode (noc- 
breakQ) and ECHO mode (echoQ) at the same time. 
Depending on the state of the tty (7) driver when each 
character is typed, the program may produce undesirable 
results. 

If keypad(win, TRUE) has been called, and a function key 
is pressed, the token for that function key will be returned 
instead of the raw characters. (See keypadQ under "Input 
Options Setting.") Possible function keys are defined in 
<curses.h> with integers beginning with 0401, whose 
names begin with KEY_. If a character is received that 
could be the beginning of a function key (such as escape), 
curses will set a timer. If the remainder of the sequence is 
not received within the designated time, the character will 
be passed through, otherwise the function key value will 
be returned. For this reason, on many terminals, there 
will be a delay after a user presses the escape key before 
the escape is returned to the program. (Use by a pro- 
grammer of the escape key for a single character routine is 
discouraged. Also see notimeoutQ below.) 

Note that getchQ, mvgetchQ, and mvwgetchQ are 
macros. 

getstr(str) 
wgetstr(win, str) 
mvgetstr(y, x, str) 
mvwgetstr(win, y, x, str) 

A series of calls to getchQ is made, until a newline, car- 
riage return, or enter key is received. The resulting value 
is placed in the area pointed at by the character pointer 



433 




CURSES(3X) 



(Terminal Information Utilities) 



CURSES(3X) 



str. The user's erase and kill characters are interpreted. 
As in mvgetch(), no refreshQ is done between the 
move() and getstrQ within the routines mvgetstr() and 
mvwgetstr( ). 

Note that getstrQ, mvgetstrQ, and mvwgetstrQ are 
macros. 

flushinp( ) 

ungetch(c) 

inch( ) 
winch(win) 
mvinch(y, x) 

mvwinch(win, y, x) The character, of type chtype, at the current position in 
the named window is returned. If any attributes are set 
for that position, their values will be OR'ed into the value 
returned. The predefined constants A CHARTEXT and 
A ATTRIBUTES, defined in <curses.h>, can be used with 
the C logical AND (&) operator to extract the character or 
attributes alone. 

Note that inchQ, winchQ, mvinchQ, and mvwinchQ are 
macros. 

scanw(fmt [, arg . . .]) 
wscanw(win, fmt [, arg . . .]) 
mvscanw(y, x, fmt [, arg . . .]) 
mvwscanw(win, y, x, fmt [, arg . . .]) 

These routines correspond to scanf( 3S), as do their argu- 
ments and return values. wgetstr( ) is called on the 
window, and the resulting line is used as input for the 
scan. 

vwscanw(win, fmt, ap) 

This routine is similar to vwprintwQ above in that per- 
forms a wscanwQ using a variable argument list. The 
third argument is a vajist, a pointer to a list of arguments, 
as defined in <varargs.h>. See the vprintf (3S) and 
varargs(5) manual pages for a detailed description on how 
to use variable argument lists. 

Output Options Setting 

These routines set options within curses that deal with output. All options are 
initially FALSE, unless otherwise stated. It is not necessary to turn these options 
off before calling endwinQ. 

clearok(win, bf) If enabled ( bf is TRUE), the next call to wrefreshQ with 
this window will clear the screen completely and redraw 
the entire screen from scratch. This is useful when the 



Throws away any typeahead that has been typed by the 
user and has not yet been read by the program. 

Place c back onto the input queue to be returned by the 
next call to wgetch( ). 
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contents of the screen are uncertain, or in some cases for a 
more pleasing visual effect. 

id!ok(win, bf) If enabled (bf is TRUE), curses will consider using the 

hardware "insert/delete-line" feature of terminals so 
equipped. If disabled (bf is FALSE), curses will very seldom 
use this feature. (The "insert/delete-character" feature is 
always considered.) This option should be enabled only if 
your application needs "insert/delete-line", for example, 
for a screen editor. It is disabled by default because 
"insert/delete-line" tends to be visually annoying when 
used in applications where it isn't really needed. If 
"insert/delete-line" cannot be used, curses will redraw the 
changed portions of all lines. 

leaveok(win, bf) Normally, the hardware cursor is left at the location of the 
window cursor being refreshed. This option allows the 
cursor to be left wherever the update happens to leave it. 
It is useful for applications where the cursor is not used, 
since it reduces the need for cursor motions. If possible, 
the cursor is made invisible when this option is enabled. 

setscrreg(top, bot) 

wsetscrreg(win, top, bot) 

These routines allow the user to set a software scrolling 
region in a window, top and bot are the line numbers of 
the top and bottom margin of the scrolling region. (Line 0 
is the top line of the window.) If this option and 
scrollok() are enabled, an attempt to move off the bottom 
margin line will cause all lines in the scrolling region to 
scroll up one line. (Note that this has nothing to do with 
use of a physical scrolling region capability in the ter- 
minal, like that in the DEC VT100. Only the text of the 
window is scrolled; if idlokQ is enabled and the terminal 
has either a scrolling region or "insert/delete-line" capa- 
bility, they will probably be used by the output routines.) 

Note that setscrreg( ) and wsetscrreg( ) are macros. 

scrollok(win, bf) This option controls what happens when the cursor of a 
window is moved off the edge of the window or scrolling 
region, either from a newline on the bottom line, or typing 
the last character of the last line. If disabled (bf is FALSE), 
the cursor is left on the bottom line at the location where 
the offending character was entered. If enabled (bf is 
TRUE), wrefreshQ is called on the window, and then the 
physical terminal and window are scrolled up one line. 
(Note that in order to get the physical scrolling effect on 
the terminal, it is also necessary to call idlokQ.) 
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nl() 

non-IQ These routines control whether newline is translated into 

carriage return and linefeed on output, and whether return 
is translated into newline on input. Initially, the transla- 
tions do occur. By disabling these translations using 
nonlQ, curses is able to make better use of the linefeed 
capability, resulting in faster cursor motion. 

Input Options Setting 

These routines set options within curses that deal with input. The options 

involve using ioctl( 2) and therefore interact with curses routines. It is not neces- 
sary to turn these options off before calling endwinQ. 

For more information on these options, see Chapter 10 of the Programmer's 

Guide. 

cbreakQ 

nocbreakQ These two routines put the terminal into and out of 

CBREAK mode, respectively. In CBREAK mode, characters 
typed by the user are immediately available to the pro- 
gram and erase/kill character processing is not performed. 
When in NOCBREAK mode, the tty driver will buffer char- 
acters typed until a newline or carriage return is typed. 
Interrupt and flow-control characters are unaffected by 
this mode (see termio(7)). Initially the terminal may or 
may not be in CBREAK mode, as it is inherited, therefore, a 
program should call cbreakQ or riocbreakQ explicitly. 
Most interactive programs using curses will set CBREAK 
mode. 

Note that cbreakQ overrides rawQ. See getchQ under 
"Input" for a discussion of how these routines interact with 
echo( ) and noecho( ). 

echbQ 

noechoQ These routines control whether characters typed by the 

user are echoed by getch( ) as they are typed. Echoing by 
the tty driver is always disabled, but initially getch( ) is in 
ECHO mode, so characters typed are echoed. Authors of 
most interactive programs prefer to do their own echoing 
in a controlled area of the screen, or not to echo at all, so 
they disable echoing by calling noechoQ. See getchQ 
under "Input" for a discussion of how these routines 
interact with cbreakQ and nocbreakQ. 

halfdelay(tenths) Half-delay mode is similar to CBREAK mode in that char- 
acters typed by the user are immediately available to the 
program. However, after blocking for tenths tenths of 
seconds, ERR will be returned if nothing has been typed. 
tenths must be a number between 1 and 255. Use noc- 
breakQ to leave half-delay mode. 
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meta(win, bf) 
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raw() 
noraw( ) 



typeahead(fildes) 
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If this option is enabled, when an interrupt key is pressed 
on the keyboard (interrupt, break, quit) all output in the 
tty driver queue will be flushed, giving the effect of faster 
response to the interrupt, but causing curses to have the 
wrong idea of what is on the screen. Disabling the option 
prevents the flush. The default for the option is inherited 
from the tty driver settings. The window argument is 
ignored. 

This option enables the keypad of the user's terminal. If 
enabled, the user can press a function key (such as an 
arrow key) and wgetch( ) will return a single value 
representing the function key, as in KEY LEFT. If disabled, 
curses will not treat function keys specially and the pro- 
gram would have to interpret the escape sequences itself. 
If the keypad in the terminal can be turned on (made to 
transmit) and off (made to work locally), turning on this 
option will cause the terminal keypad to be turned on 
when wgetch( ) is called. 

If enabled, characters returned by wgetch( ) are 
transmitted with all 8 bits, instead of with the highest bit 
stripped. In order for meta() to work correctly, the km 
(has meta key) capability has to be specified in the ter- 
minal's terminfo(4) entry. 

This option causes wgetch() to be a non-blocking call. If 
no input is ready, wgetch() will return ERR. If disabled, 
wgetch( ) will hang until a key is pressed. 

While interpreting an input escape sequence, wgetch() 
will set a timer while waiting for the next character. If 
notimeout(win, TRUE) is called, then wgetchQ will not 
set a timer. The purpose of the timeout is to differentiate 
between sequences received from a function key and those 
typed by a user. 



The terminal is placed into or out of raw mode. RAW 
mode is similar to CBREAK mode, in that characters typed 
are immediately passed through to the user program. The 
differences are that in RAW mode, the interrupt, quit, 
suspend, and flow control characters are passed through 
uninterpreted, instead of generating a signal. RAW mode 
also causes 8 -bit input and output. The behavior of the 
BREAK key depends on other bits in the tty (7) driver that 
are not set by curses, 

curses does "line-breakout optimization" by looking for 
typeahead periodically while updating the screen. If input 
is found, and it is coming from a tty, the current update 
will be postponed until refreshQ or doupdate( ) is called 
again. This allows faster response to commands typed in 
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advance. Normally, the file descriptor for the input FILE 
pointer passed to newterm(), or stdin in the case that 
initscr() was used, will be used to do this typeahead 
checking. The typeaheadQ routine specifies that the file 
descriptor fildes is to be used to check for typeahead 
instead. If fildes is — 1, then no typeahead checking will be 
done. 

Note that fildes is a file descriptor, not a <stdio.h> FILE 
pointer. 

Environment Queries 

baudrateQ Returns the output speed of the terminal. The number 

returned is in bits per second, for example, 9600, and is an 
integer. 

char erasechar( ) The user's current erase character is returned. 

has_ic() True if the terminal has insert- and delete-character capa- 

bilities. 

has_il() True if the terminal has insert- and delete-line capabilities, 

or can simulate them using scrolling regions. This might 
be used to check to see if it would be appropriate to turn 
on physical scrolling using scrollok(). 

char killchar( ) The user's current line-kill character is returned. 

char *longname() This routine returns a pointer to a static area containing a 
verbose description of the current terminal. The max- 
imum length of a verbose description is 128 characters. It 
is defined only after the call to initscr() or newterm(). 
The area is overwritten by each call to newterm() and is 
not restored by settermQ, so the value should be saved 
between calls to newterm() if longnameQ is going to be 
used with multiple terminals. 

Soft Labels 

If desired, curses will manipulate the set of soft function-key labels that exist on 
many terminals. For those terminals that do not have soft labels, if you want to 
simulate them, curses will take over the bottom line of stdscr, reducing the size 
of stdscr and the variable LINES, curses standardizes on 8 labels of 8 characters 
each. 

slkjnit(labfmt) In order to use soft labels, this routine must be called 
before initscr() or newterm() is called. If initscrQ winds 
up using a line from stdscr to emulate the soft labels, then 
labfmt determines how the labels are arranged on the 
screen. Setting labfmt to 0 indicates that the labels are to 
be arranged in a 3-2-3 arrangement; 1 asks for a 4-4 
arrangement. 

slk_set(labnum, label, labfmt) 

labnum is the label number, from 1 to 8. label is the string 
to be put on the label, up to 8 characters in length. A 
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NULL string or a NULL pointer will put up a blank label. 
labfmt is one of 0, 1 or 2, to indicate whether the label is 
to be left-justified, centered, or right- justified within the 
label. 

slk_refresh( ) 

slk_noutrefresh( ) These routines correspond to the routines wrefreshQ and 
wnoutrefreshQ. Most applications would use 
slk_noutrefresh( ) because a wrefreshQ will most likely 
soon follow. 

char *slk_label(labnum) 

The current label for label number labnum, with leading 
and trailing blanks stripped, is returned. 

slk_clearQ The soft labels are cleared from the screen. 

slk_restore( ) The soft labels are restored to the screen after a 

slkclearQ. 

slk_touch() All of the soft labels are forced to be output the next time 

a slk_noutrefresh( ) is performed. 

Low-Level curses Access 

The following routines give low-level access to various curses functionality. 

These routines typically would be used inside of library routines. 

def_prog_mode( ) 

def_shell_mode( ) Save the current terminal modes as the "program" (in 
curses) or "shell" (not in curses) state for use by the 
reset_prog_mode( ) and reset_shell_mode( ) routines. This 
is done automatically by initscr( ). 

reset j3rog_mode( ) 

reset_shell_mode( ) Restore the terminal to "program" (in curses) or "shell" 
(out of curses) state. These are done automatically by 
endwinQ and doupdateQ after an endwinQ, so they nor- 
mally would not be called. 

resetty( ) 

savettyQ These routines save and restore the state of the terminal 

modes. savettyQ saves the current state of the terminal in 
a buffer and resettyQ restores the state to what it was at 
the last call to savettyQ. 

getsyx(y, x) The current coordinates of the virtual screen cursor are 

returned in y and x. Like getyxQ, the variables y and x do 
not take an before them. If leaveokQ is currently 

TRUE, then -1,-1 will be returned. If lines may have 
been removed from the top of the screen using 
ripofflineQ and the values are to be used beyond just 
passing them on to setsyxQ, the value 
y+stdscr— >_yoffset should be used for those other uses. 

Note that getsyx( ) is a macro. 
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setsyx(y, x) 
ripoffline(line, init) 



scrdump(filename) 

scrrestore(filename) 

scrinit(filename) 



curs_set( visibility) 
draino(ms) 



The virtual screen cursor is set to y, x. If y and x are both 
— 1, then leaveokQ will be set. The two routines getsyxQ 
and setsyx( ) are designed to be used by a library routine 
which manipulates curses windows but does not want to 
mess up the current position of the program's cursor. The 
library routine would call getsyxQ at the beginning, do its 
manipulation of its own windows, do a wnoutrefresh( ) 
on its windows, call setsyxQ, and then call doupdateQ. 

This routine provides access to the same facility that 
slk_init( ) uses to reduce the size of the screen. 
ripofflineQ must be called before initscrQ or newtermQ 
is called. If line is positive, a line will be removed from 
the top of stdscr; if negative, a line will be removed from 
the bottom. When this is done inside initscrQ, the rou- 
tine init() is called with two arguments: a window pointer 
to the 1-line window that has been allocated and an 
integer with the number of columns in the window. 
Inside this initialization routine, the integer variables 
LINES and COLS (defined in <curses.h>) are not 
guaranteed to be accurate and wrefreshQ or doupdateQ 
must not be called. It is allowable to call wnoutrefresh( ) 
during the initialization routine. 

ripofflineQ can be called up to five times before calling 
initscrQ or newtermQ. 

The current contents of the virtual screen are written to 
the file filename. 

The virtual screen is set to the contents of filename , which 
must have been written using scr_dump(). The next call 
to doupdateQ will restore the screen to what it looked 
like in the dump file. 

The contents of filename are read in and used to initialize 
the curses data structures about what the terminal 
currently has on its screen. If the data is determined to be 
valid, curses will base its next update of the screen on this 
information rather than clearing the screen and starting 
from scratch. scr_init() would be used after initscrQ or a 
system (3S) call to share the screen with another process 
which has done a scrdumpQ after its endwinQ call. The 
data will be declared invalid if the time-stamp of the tty is 
old or the terminfo(4) capability nrrmc is true. 

The cursor is set to invisible, normal, or very visible for 
visibility equal to 0, 1 or 2. 

Wait until the output has drained enough that it will only 
take ms more milliseconds to drain completely. 
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garbagedlines(win, begline, numlines) 

This routine indicates to curses that a screen line is gar- 
baged and should be thrown away before having anything 
written over the top of it. It could be used for programs 
such as editors which want a command to redraw just a 
single line. Such a command could be used in cases 
where there is a noisy communications line and redrawing 
the entire screen would be subject to even more communi- 
cation noise. Just redrawing the single line gives some 
semblance of hope that it would show up unblemished. 
The current location of the window is used to determine 
which lines are to be redrawn. 

napms(ms) Sleep for ms milliseconds. 

Terminf o-Level Manipulations 

These low-level routines must be called by programs that need to deal directly 
with the terminf o( 4) database to handle certain terminal capabilities, such as pro- 
gramming function keys. For all other functionality, curses routines are more 
suitable and their use is recommended. 

Initially, setupterm() should be called. (Note that setuptermQ is automatically 
called by initscrQ and newterm().) This will define the set of terminal- 
dependent variables defined in the terminf o( 4) database. The terminf o( 4) vari- 
ables lines and columns (see terminf o( 4)) are initialized by setuptermQ as fol- 
lows: if the environment variables LINES and COLUMNS exist, their values are 
used. If the above environment variables do not exist and the program is run- 
ning in a layer (see layers( 1)), the size of the current layer is used. Otherwise, 
the values for lines and columns specified in the terminf o( 4) database are used. 

The header files <curses.h> and <term.h> should be included, in this order, 
to get the definitions for these strings, numbers, and flags. Parameterized strings 
should be passed through tparmQ to instantiate them. All terminf o{ 4) strings 
(including the output of tparmQ) should be printed with tputsQ or putpQ. 
Before exiting, reset_shell_mode( ) should be called to restore the tty modes. 
Programs which use cursor addressing should output enter_ca_mode upon 
startup and should output exit ca mode before exiting (see terminf o( 4)). (Pro- 
grams desiring shell escapes should call reset_shell_mode( ) and output 
exit ca mode before the shell is called and should output enter ca mode and 
call reset jprog mode( ) after returning from the shell. Note that this is different 
from the curses routines (see endwin( )). 

setupterm(term, fildes, errret) 

Reads in the terminfo( 4) database, initializing the ter- 
minf o (4) structures, but does not set up the output virtuali- 
zation structures used by curses. The terminal type is in 
the character string term; if term is NULL, the environment 
variable TERM will be used. All output is to the file 
descriptor fildes. If errret is not NULL, then setuptermQ 
will return OK or ERR and store a status value in the 
integer pointed to by errret. A status of 1 in errret is 
normal, 0 means that the terminal could not be found, and 
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— 1 means that the terminfo( 4) database could not be 
found. If errret is NULL, setupterm() will print an error 
message upon finding an error and exit. Thus, the sim- 
plest call is setupterm ((char *)0, 1, (int *)0), which uses 
all the defaults. 

The terminfo{ 4) boolean, numeric and string variables are 
stored in a structure of type TERMINAL. After setup- 
term() returns successfully, the variable curterm (of type 
TERMINAL *) is initialized with all of the information that 
the terminfo( 4) boolean, numeric and string variables refer 
to. The pointer may be saved before calling setupterm() 
again. Further calls to setupterm() will allocate new 
space rather than reuse the space pointed to by cur term. 

set_curterm(nterm) nterm is of type TERMINAL *. set_curterm( ) sets the vari- 
able cur_term to nterm, and makes all of the terminfo( 4) 
boolean, numeric and string variables use the values from 
nterm. 

del_curterm(oterm) oterm is of type TERMINAL *. del_curterm( ) frees the 
space pointed to by oterm and makes it available for 
further use. If oterm is the same as cur_term, then refer- 
ences to any of the terminfo( 4) boolean, numeric and 
string variables thereafter may refer to invalid memory 
locations until another setupterm( ) has been called. 

restartterm(term, fildes, errret) 

Like setup term( ) after a memory restore. 

char *tparm(str, p j7 p , . . ., p^) 

Instantiate the string str with parms p.. A pointer is 
returned to the result of str with the parameters applied. 

tputs(str, count, putc) 

Apply padding to the string str and output it. str must be 
a terminfo( 4) string variable or the return value from 
tparm(), tgetstrQ, tigetstrQ or tgotoQ. count is the 
number of lines affected, or 1 if not applicable. putc() is a 
putchar( 3S)-like routine to which the characters are 
passed, one at a time. 

A routine that calls tputs (str, 1, putcharQ). 

Output a string that puts the terminal in the video attri- 
bute mode attrs, which is any combination of the attri- 
butes listed below. The characters are passed to the 
putchar (3S)-like routine putc(). 

Like vidputsQ, except that it outputs through putchar( 3S). 

mvcur(oldrow, oldcol, newrow, newcol) 

Low-level cursor motion. 



putp(str) 

vidputs(attrs, putc) 



vidattr(attrs) 
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The following routines return the value of the capability corresponding to the 
terminfo( 4) capname passed to them, such as xenl. 

tigetflag(capname) The value — 1 is returned if capname is not a boolean capa- 
bility. 

tigetnum(capname) The value —2 is returned if capname is not a numeric capa- 
bility. 

tigetstr(capname) The value (char *) —1 is returned if capname is not a string 
capability. 

char *boolnames[ ], *boolcodes[ ], *boolfnames[] 
char *numnames[], *numcodes[], *numfnames[] 
char *strnames[], *strcodes[], *strfnames[] 

These null-terminated arrays contain the capnames, the 
termcap codes, and the full C names, for each of the ter - 
minfo(4) variables. 

Termcap Emulation 

These routines are included as a conversion aid for programs that use the 
termcap library. Their parameters are the same and the routines are emulated 
using the terminfo( 4) database. 

tgetent(bp, name) Look up termcap entry for name. The emulation ignores 
the buffer pointer bp. 

tgetflag(codename) Get the boolean entry for codename. 
tgetnum(codes) Get numeric entry for codename. 

char *tgetstr(codename, area) 

Return the string entry for codename. If area is not NULL, 
then also store it in the buffer pointed to by area and 
advance area. tputs() should be used to output the 
returned string. 

char *tgoto(cap, col, row) 

Instantiate the parameters into the given capability. The 
output from this routine is to be passed to tputs( ). 

tputs(str, affcnt, putc) 

See tputs() above, under "Terminfo-Level Manipulations”. 



Turn off and on debugging trace output when using the 
debug version of the curses library, /usr /lib /libdcurses.a. 
This facility is available only to customers with a source 
license. 

This macro expands to a character string which is a print- 
able representation of the character c. Control characters 
are displayed in the "X notation. Printing characters are 
displayed as is. 



Miscellaneous 
traceoff ( ) 
traceon() 



unctrl(c) 
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unctrl( ) is a macro, defined in <unctrl.h>, which is 
automatically included by < curses.h>. 

char *keyname(c) A character string corresponding to the key c is returned. 

filterQ This routine is one of the few that is to be called before 

initscr( ) or newterm( ) is called. It arranges things so that 
curses thinks that there is a 1-line screen, curses will not 
use any terminal capabilities that assume that they know 
what line on the screen the cursor is on. 

Use of cursor 

The special window curscr can be used in only a few routines. If the window 
argument to clearokQ is curscr, the next call to wrefreshQ with any window 
will cause the screen to be cleared and repainted from scratch. If the window 
argument to wrefresh( ) is curscr, the screen is immediately cleared and 
repainted from scratch. (This is how most programs would implement a 
"repaint-screen" routine.) The source window argument to overlayQ, 
overwriteQ, and copywinQ may be curscr, in which case the current contents 
of the virtual terminal screen will be accessed. 

Obsolete Calls 

Various routines are provided to maintain compatibility in programs written for 
older versions of the curses library. These routines are all emulated as indicated 
below. 



crmode( ) 
fixterm( ) 
gettmodeQ 
nocrmode( ) 
resetterm( ) 
saveterm( ) 
setterm( ) 



Replaced by cbreakQ. 

Replaced by reset_prog_mode( ). 
A no-op. 

Replaced by nocbreak(). 
Replaced by reset_shell_mode( ). 
Replaced by def_prog_mode( ). 
Replaced by setupterm( ). 



ATTRIBUTES 

The following video attributes, defined in <curses.h>, can be passed to the 
routines attron( ), attroff( ), and attrset( ), or OR'ed with the characters passed to 
addchQ. 



ASTANDOUT 

AUNDERLINE 

AREVERSE 

A_BUNK 

ADIM 

ABOLD 

AALT CHARSET 
ACHARTEXT 



Terminal's best highlighting mode 

Underlining 

Reverse video 

Blinking 

Half bright 

Extra bright or bold 

Alternate character set 

Bit-mask to extract character (described under winch( )) 
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AATTRIBUTES Bit-mask to extract attributes (described under winch( )) 
ANORMAL Bit mask to reset all attributes off 

(for example: attrset (A NORMAL) 

FUNCTION-KEYS 

The following function keys, defined in <curses.h>, might be returned by 
getch() if keypadQ has been enabled. Note that not all of these may be sup- 
ported on a particular terminal if the terminal does not transmit a unique code 
when the key is pressed or the definition for the key is not present in the ter- 
minfo(4) database. 



Name 


Value 


Key name 


KEYBREAK 


0401 


break key (unreliable) 


KEYDOWN 


0402 


The four arrow keys . . . 


KEYJJP 


0403 


KEYLEFT 


0404 




KEYRIGHT 


0405 




KEYHOME 


0406 


Home key (upward+left arrow) 


KEYBACKSPACE 


0407 


backspace (unreliable) 


KEYFO 


0410 


Function keys. Space for 64 keys is reserved. 


KEY F(n) 


(KEY F0+(n)) 


Formula for f^. 
Delete line 


KEYDL 


0510 


KEY IL 


0511 


Insert line 


KEYDC 


0512 


Delete character 


KEY IC 


0513 


Insert char or enter insert mode 


KEY EIC 


0514 


Exit insert char mode 


KEY CLEAR 


0515 


Clear screen 


KEY EOS 


0516 


Clear to end of screen 


KEYEOL 


0517 


Clear to end of line 


KEYSF 


0520 


Scroll 1 line forward 


KEY_SR 


0521 


Scroll 1 line backwards (reverse) 


KEY NPAGE 


0522 


Next page 


KEYPPAGE 


0523 


Previous page 


KEY STAB 


0524 


Set tab 


KEYCTAB 


0525 


Clear tab 


KEY CATAB 


0526 


Clear all tabs 


KEYENTER 


0527 


Enter or send 


KEY SRESET 


0530 


soft (partial) reset 


KEYRESET 


0531 


reset or hard reset 


KEYPRINT 


0532 


print or copy 


KEYLL 


0533 


home down or bottom (lower left) 
keypad is arranged like this: 

A1 up A3 
left B2 right 
Cl down C3 


KEYAl 


0534 


Upper left of keypad 


KEY A3 


0535 


Upper right of keypad 


KEYB2 


0536 


Center of keypad 


KEY Cl 


0537 


Lower left of keypad 
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KEY_C3 


0540 


Lower right of keypad 


KEY BTAB 


0541 


Back tab key 


KEY BEG 


0542 


beg(inning) key 


KEY_CANCEL 


0543 


cancel key 


KEY_CLOSE 


0544 


close key 


KEY_COMMAND 


0545 


cmd (command) key 


KEYCOPY 


0546 


copy key 


KEYCREATE 


0547 


create key 


KEYEND 


0550 


end key 


KEYEXIT 


0551 


exit key 


KEYFIND 


0552 


find key 


KEYHELP 


0553 


help key 


KEY MARK 


0554 


mark key 


KEYMESSAGE 


0555 


message key 


KEY MOVE 


0556 


move key 


KEYNEXT 


0557 


next object key 


KEY OPEN 


0560 


open key 


KEYOPTIONS 


0561 


options key 


KEYPREVIOUS 


0562 


previous object key 


KEY REDO 


0563 


redo key 


KEYREFERENCE 


0564 


ref(erence) key 


KEY REFRESH 


0565 


refresh key 


KEYREPLACE 


0566 


replace key 


KEYRESTART 


0567 


restart key 


KEYRESUME 


0570 


resume key 


KEY SAVE 


0571 


save key 


KEY SBEG 


0572 


shifted beginning key 


KEY SCANCEL 


0573 


shifted cancel key 


KEY SCOMMAND 


0574 


shifted command key 


KEYSCOPY 


0575 


shifted copy key 


KEY SCREATE 


0576 


shifted create key 


KEYSDC 


0577 


shifted delete char key 


KEY SDL 


0600 


shifted delete line key 


KEYSELECT 


0601 


select key 


KEY_SEND 


0602 


shifted end key 


KEY SEOL 


0603 


shifted clear line key 


KEYSEXIT 


0604 


shifted exit key 


KEY SFIND 


0605 


shifted find key 


KEYSHELP 


0606 


shifted help key 


KEY SHOME 


0607 


shifted home key 


KEY SIC 


0610 


shifted input key 


KEY SLEFT 


0611 


shifted left arrow key 


KEY SMESSAGE 


0612 


shifted message key 


KEYSMOVE 


0613 


shifted move key 


KEY_SNEXT 


0614 


shifted next key 


KEYSOPTIONS 


0615 


shifted options key 


KEY_SPREVIOUS 


0616 


shifted prev key 


KEY_SPRINT 


0617 


shifted print key 


KEY SREDO 


0620 


shifted redo key 
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KEY SREPLACE 


0621 


shifted replace key 


KEYSRIGHT 


0622 


shifted right arrow 


KEY SRSUME 


0623 


shifted resume key 


KEYSSAVE 


0624 


shifted save key 


KEY SSUSPEND 


0625 


shifted suspend key 


KEYSUNDO 


0626 


shifted undo key 


KEYSUSPEND 


0627 


suspend key 


KEYUNDO 


0630 


undo key 



LINE GRAPHICS 

The following variables may be used to add line-drawing characters to the 
screen with waddchQ. When defined for the terminal, the variable will have 
the A ALTCHARSET bit turned on. Otherwise, the default charcter listed below 
will be stored in the variable. The names were chosen to be consistent with the 
DEC VT100 nomenclature. 



Name 


Default 


Glyph Description 


ACSULCORNER 


+ 


upper left corner 


ACS LLCORNER 


+ 


lower left corner 


ACSURCORNER 


+ 


upper right corner 


ACSLRCORNER 


+ 


lower right corner 


ACS RTEE 


+ 


right tee (— |) 


ACSLTEE 


+ 


left tee (|-) 


ACS BTEE 


+ 


bottom tee (1) 


ACS TTEE 


+ 


top tee (J) 


ACSHLINE 


— 


horizontal line 


ACS VLINE 


1 


vertical line 


ACS PLUS 


+ 


plus 


ACS SI 


— 


scan line 1 


ACSS9 




scan line 9 


ACSDIAMOND 


+ 


diamond 


ACSCKBOARD 




checker board (stipple) 


ACSDEGREE 


' 


degree symbol 


ACSPLMINUS 


# 


plus/minus 


ACSBULLET 


o 


bullet 


ACSLARROW 


< 


arrow pointing left 


ACS_RARROW 


> 


arrow pointing right 


ACS_D ARROW 


V 


arrow pointing down 


ACS_U ARROW 


- 


arrow pointing up 


ACS BOARD 


# 


board of squares 


ACS LANTERN 


# 


lantern symbol 


ACS BLOCK 


# 


solid square block 



DIAGNOSTICS 

All routines return the integer OK upon successful completion and the integer 
ERR upon failure, unless otherwise noted in the preceding routine descriptions. 
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All macros return the value of their w version, except setscrregQ, wsetscrreg( ), 
getsyxQ, getyx( ), getbegyQ, getmaxyx(). For these macros, no useful value is 
returned. 

Routines that return pointers always return (type *) NULL on error. 

BUGS 

Currently typeahead checking is done using a nodelay read followed by an 
ungetchQ of any character that may have been read. Typeahead checking is 
done only if wgetch( ) has been called at least once. This will be changed when 
proper kernel support is available. Programs which use a mixture of their own 
input routines with curses input routines may wish to call typeahead(— 1) to turn 
off typeahead checking. 

The argument to napms( ) is currently rounded up to the nearest second, 
draino (ms) only works for ms equal to 0. 

WARNINGS 

To use the new curses features, use the Release 3.0 version of curses on UNIX 
System Release 3.0. All programs that ran with System V Release 2 curses will 
run with System V Release 3.0. You may link applications with object files 
based on the Release 2 curses / terminfo with the Release 3.0 libcurses.a library. 
You may link applications with object files based on the Release 3.0 
curses /terminfo with the Release 2 libcurses.a library, so long as the application 
does not use the new features in the Release 3.0 curses /terminfo. 

The plotting library plot( 3X) and the curses library curses( 3X) both use the 
names erase() and move(). The curses versions are macros. If you need both 
libraries, put the plot( 3X) code in a different source file than the curses( 3X) code, 
and/or #undef move() and eraseO in the plot( 3X) code. 

Between the time a call to initscr( ) and endwin( ) has been issued, use only the 
routines in the curses library to generate output. Using system calls or the "stan- 
dard I/O package” (see stdio( 3S)) for output during that time can cause 
unpredictable results. 

SEE ALSO 

cc(l), ld(l), ioctl(2), plot(3X), putc(3S), scanf(3S), stdio(3S), system(3S), 
vprintf(3S), profile(4), term(4), terminfo(4), varargs(5). 
termio(7), tty(7) in the System Administrator's Reference Manual. 

Chapter 10 of the Programmer's Guide. 
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NAME 

directory: opendir, readdir, telldir, seekdir, rewinddir, closedir — directory opera- 
tions 

SYNOPSIS 

#include <sys/types.h> 

#include <dirent.h> 

DIR *opendir (filename) 
char *filename; 

struct dirent *readdir (dirp) 

DIR *dirp; 

long telldir (dirp) 

DIR *dirp; 

void seekdir (dirp, loc) 

DIR *dirp; 
long loc; 

void rewinddir (dirp) 

DIR *dirp; 

void closedir(dirp) 

DIR *dirp; 

DESCRIPTION 

Opendir opens the directory named by filename and associates a directory stream 
with it. Opendir returns a pointer to be used to identify the directory stream in 
subsequent operations. The pointer NULL is returned if filename cannot be 
accessed or is not a directory, or if it cannot malloc( 3X) enough memory to hold 
a DIR structure or a buffer for the directory entries. 

Readdir returns a pointer to the next active directory entry. No inactive entries 
are returned. It returns NULL upon reaching the end of the directory or upon 
detecting an invalid location in the directory. 

Telldir returns the current location associated with the named directory stream. 

Seekdir sets the position of the next readdir operation on the directory stream. 
The new position reverts to the one associated with the directory stream when 
the telldir operation from which loc was obtained was performed. Values 
returned by telldir are good only if the directory has not changed due to com- 
paction or expansion. This is not a problem with System V, but it may be with 
some file system types. 

Rewinddir resets the position of the named directory stream to the beginning of 
the directory. 

Closedir closes the named directory stream and frees the DIR structure. 

The following errors can occur as a result of these operations. 
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opendir: 

[ENOTDIR] A component of filename is not a directory. 

[EACCES] A component of filename denies search permission. 

[EMFILE] The maximum number of file descriptors are currently open. 

[EFAULT] Filename points outside the allocated address space. 

readdir: 

[ENOENT] The current file pointer for the directory is not located at a valid 

entry. 

[EBADF] The file descriptor determined by the DIR stream is no longer 

valid. This results if the DIR stream has been closed. 

telldir, seekdir, and closedir: 

[EBADF] The file descriptor determined by the DIR stream is no longer 

valid. This results if the DIR stream has been closed. 

EXAMPLE 

Sample code which searches a directory for entry name: 

dirp = opendir( ); 

while ( (dp = readdir( dirp )) != NULL ) 

if ( strcmp( dp->d_name, name ) == 0 ) 

closedir( dirp ); 
return FOUND; 

} 

closedir( dirp ); 
return NOTFOUND; 

SEE ALSO 

getdents(2), dirent(4). 

WARNINGS 

Rewinddir is implemented as a macro, so its function address cannot be taken. 

NAME 

ldahread — read the archive header of a member of an archive file 
SYNOPSIS 

#include <stdio.h> 

#include <ar.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int ldahread (ldptr, arhead) 

LDFILE *ldptr; 

ARCHDR *arhead; 
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DESCRIPTION 

If TYPE (Idptr) is the archive file magic number, Idahread reads the archive header 
of the common object file currently associated with Idptr into the area of 
memory beginning at arhead. 

Idahread returns SUCCESS or FAILURE. Idahread will fail if TYPE (Idptr) does not 
represent an archive file, or if it cannot read the archive header. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), ldopen(3X), ldfcn(4), ar(4). 
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NAME 

ldclose, ldaclose — close a common object file 
SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int ldclose (Idptr) 

LDFILE *ldptr; 

int ldaclose (Idptr) 

LDFILE *ldptr; 

DESCRIPTION 

Ldopen( 3X) and ldclose are designed to provide uniform access to both simple 
object files and object files that are members of archive files. Thus an archive of 
common object files can be processed as if it were a series of simple common 
object files. 

If TYPE (Idptr) does not represent an archive file, ldclose will close the file and 
free the memory allocated to the LDFILE structure associated with Idptr. If 
TYPE (Idptr) is the magic number of an archive file, and if there are any more 
files in the archive, ldclose will reinitialize OFFSET (Idptr) to the file address of the 
next archive member and return FAILURE. The LDFILE structure is prepared for 
a subsequent ldopen( 3X). In all other cases, ldclose returns SUCCESS. 

Ldaclose closes the file and frees the memory allocated to the LDFILE structure 
associated with Idptr regardless of the value of TYPE (Idptr), Ldaclose always 
returns SUCCESS. The function is often used in conjunction with Idaopen. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

fclose(3S), ldopen(3X), ldfcn(4). 
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NAME 

ldfhread — read the file header of a common object file 
SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int ldfhread (ldptr, filehead) 

LDFILE * ldptr; 

FILHDR * filehead; 

DESCRIPTION 

ldfhread reads the file header of the common object file currently associated with 
ldptr into the area of memory beginning at filehead. 

ldfhread returns SUCCESS or FAILURE, ldfhread will fail if it cannot read the file 
header. 

In most cases the use of ldfhread can be avoided by using the macro 
HEADER(Zdpfr) defined in ldfcn.h [see ldfcn (4)]. The information in any field, 
fieldname, of the file header may be accessed using HEADER(ldptr).fieldname. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), ldopen(3X), ldfcn(4). 
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NAME 

ldgetname — retrieve symbol name for common object file symbol table entry 
SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <syms.h> 

#include <ldfcn.h> 

char *ldgetname (ldptr, symbol) 

LDFILE *ldptr; 

SYMENT * symbol; 

DESCRIPTION 

ldgetname returns a pointer to the name associated with symbol as a string. The 
string is contained in a static buffer local to ldgetname that is overwritten by 
each call to ldgetname, and therefore must be copied by the caller if the name is 
to be saved. 

ldgetname can be used to retrieve names from object files without any backward 
compatibility problems, ldgetname will return NULL (defined in stdio.h) for an 
object file if the name cannot be retrieved. This situation can occur: 

— if the "string table" cannot be found, 

— if not enough memory can be allocated for the string table, 

— if the string table appears not to be a string table (for example, if an aux- 

iliary entry is handed to ldgetname that looks like a reference to a name 
in a nonexistent string table), or 

— if the name's offset into the string table is past the end of the string 
table. 

Typically, ldgetname will be called immediately after a successful call to Idtbread 
to retrieve the name associated with the symbol table entry filled by Idtbread. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), ldopen(3X), ldtbread(3X), ldtbseek(3X), ldfcn(4). 
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NAME 

ldlread, ldlinit, ldlitem — manipulate line number entries of a common object file 
function 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <linenum.h> 

#include <ldfcn.h> 

int ldlread(ldptr, fcnindx, linenum, linent) 

LDFILE *Idptr; 
long fcnindx; 
unsigned short linenum; 

LINENO *linent; 

int ldlinit(ldptr, fcnindx) 

LDFILE *ldptr; 
long fcnindx; 

int ldlitem(ldptr, linenum, linent) 

LDFILE *ldptr; 
unsigned short linenum; 

LINENO * linent; 

DESCRIPTION 

ldlread searches the line number entries of the common object file currently 
associated with Idptr. ldlread begins its search with the line number entry for 
the beginning of a function and confines its search to the line numbers associ- 
ated with a single function. The function is identified by fcnindx , the index of its 
entry in the object file symbol table, ldlread reads the entry with the smallest 
line number equal to or greater than linenum into the memory beginning at 
linent. 

Ldlinit and ldlitem together perform exactly the same function as ldlread. After 
an initial call to ldlread or ldlinit, ldlitem may be used to retrieve a series of line 
number entries associated with a single function. Ldlinit simply locates the line 
number entries for the function identified by fcnindx. Ldlitem finds and reads the 
entry with the smallest line number equal to or greater than linenum into the 
memory beginning at linent. 

ldlread, ldlinit, and ldlitem each return either SUCCESS or FAILURE, ldlread will 
fail if there are no line number entries in the object file, if fcnindx does not index 
a function entry in the symbol table, or if it finds no line number equal to or 
greater than linenum. Ldlinit will fail if there are no line number entries in the 
object file or if fcnindx does not index a function entry in the symbol table. 
Ldlitem will fail if it finds no line number equal to or greater than linenum. 

The programs must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), ldopen(3X), ldtbindex(3X), ldfcn(4). 
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NAME 

ldlseek, ldnlseek — seek to line number entries of a section of a common object 
file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int ldlseek (ldptr, sectindx) 

LDFILE *ldptr; 
unsigned short sectindx; 

int ldnlseek (ldptr, sectname) 

LDFILE *ldptr; 
char *sectname; 

DESCRIPTION 

ldlseek seeks to the line number entries of the section specified by sectindx of the 
common object file currently associated with ldptr. 

Ldnlseek seeks to the line number entries of the section specified by sectname. 

ldlseek and ldnlseek return SUCCESS or FAILURE, ldlseek will fail if sectindx is 
greater than the number of sections in the object file; ldnlseek will fail if there is 
no section name corresponding with *sectname. Either function will fail if the 
specified section has no line number entries or if it cannot seek to the specified 
line number entries. 

Note that the first section has an index of one. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), ldopen(3X), ldshread(3X), ldfcn(4). 
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NAME 

ldohseek — seek to the optional file header of a common object file 
SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int ldohseek (ldptr) 

LDFILE *ldptr; 

DESCRIPTION 

ldohseek seeks to the optional file header of the common object file currently 
associated with ldptr. 

ldohseek returns SUCCESS or FAILURE, ldohseek will fail if the object file has no 
optional header or if it cannot seek to the optional header. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), ldopen(3X), ldfhread(3X), ldfcn(4). 
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NAME 

ldopen, ldaopen — open a common object file for reading 
SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

LDFILE *ldopen (filename, ldptr) 
char *filename; 

LDFILE *ldptr; 

LDFILE *ldaopen (filename, oldptr) 
char *filename; 

LDFILE * oldptr; 

DESCRIPTION 

ldopen and ldclose( 3X) are designed to provide uniform access to both simple 
object files and object files that are members of archive files. Thus an archive of 
common object files can be processed as if it were a series of simple common 
object files. 

If ldptr has the value NULL, then ldopen will open filename and allocate and ini- 
tialize the LDFILE structure, and return a pointer to the structure to the calling 
program. 

If ldptr is valid and if TYPE (ldptr) is the archive magic number, ldopen will reini- 
tialize the LDFILE structure for the next archive member of filename. 

ldopen and ldclose ( 3X) are designed to work in concert. Ldclose will return 
FAILURE only when TYPE (ldptr) is the archive magic number and there is 
another file in the archive to be processed. Only then should ldopen be called 
with the current value of ldptr. In all other cases, in particular whenever a new 
filename is opened, ldopen should be called with a NULL ldptr argument. 

The following is a prototype for the use of ldopen and ldclose ( 3X). 

/* for each filename to be processed */ 

ldptr = NULL; 
do 
{ 

if ( (ldptr = ldopen(filename, ldptr)) != NULL ) 

/* check magic number */ 

/* process the file */ 

} while (ldclose(ldptr) — FAILURE ); 

If the value of oldptr is not NULL, ldaopen will open filename anew and allocate 
and initialize a new LDFILE structure, copying the TYPE, OFFSET, and HEADER 
fields from oldptr. Ldaopen returns a pointer to the new LDFILE structure. This 
new pointer is independent of the old pointer, oldptr. The two pointers may be 
used concurrently to read separate parts of the object file. For example, one 
pointer may be used to step sequentially through the relocation information, 
while the other is used to read indexed symbol table entries. 
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Both Idopen and Idaopen open filename for reading. Both functions return NULL 
if filename cannot be opened, or if memory for the LDFILE structure cannot be 
allocated. A successful open does not insure that the given file is a common 
object file or an archived object file. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

fopen(3S), ldclose(3X), ldfcn(4). 
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NAME 

ldrseek, ldnrseek — seek to relocation entries of a section of a common object file 
SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int ldrseek (Idptr, sectindx) 

LDFILE *ldptr; 
unsigned short sectindx; 

int ldnrseek (Idptr, sectname) 

LDFILE *ldptr; 
char *sectname; 

DESCRIPTION 

ldrseek seeks to the relocation entries of the section specified by sectindx of the 
common object file currently associated with Idptr. 

Ldnrseek seeks to the relocation entries of the section specified by sectname. 

ldrseek and ldnrseek return SUCCESS or FAILURE, ldrseek will fail if sectindx is 
greater than the number of sections in the object file; ldnrseek will fail if there is 
no section name corresponding with sectname. Either function will fail if the 
specified section has no relocation entries or if it cannot seek to the specified 
relocation entries. 

Note that the first section has an index of one. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), ldopen(3X), ldshread(3X), ldfcn(4j. 
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NAME 

ldshread, ldnshread — read an indexed/named section header of a common 
object file 

SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <scnhdr.h> 

#include <ldfcn.h> 

int ldshread (ldptr, sectindx, secthead) 

LDFILE *ldptr; 
unsigned short sectindx; 

SCNHDR *secthead; 

int ldnshread (ldptr, sectname, secthead) 

LDFILE *ldptr; 
char *sectname; 

SCNHDR *secthead; 

DESCRIPTION 

ldshread reads the section header specified by sectindx of the common object file 
currently associated with ldptr into the area of memory beginning at secthead. 

Ldnshread reads the section header specified by sectname into the area of 
memory beginning at secthead. 

ldshread and ldnshread return SUCCESS or FAILURE, ldshread will fail if sectindx 
is greater than the number of sections in the object file; ldnshread will fail if 
there is no section name corresponding with sectname. Either function will fail if 
it cannot read the specified section header. 

Note that the first section header has an index of one. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), ldopen(3X), ldfcn(4). 
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NAME 

ldsseek, ldnsseek — seek to an indexed/named section of a common object file 
SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int ldsseek (ldptr, sectindx) 

LDFILE *ldptr; 
unsigned short sectindx; 

int ldnsseek (ldptr, sectname) 

LDFILE *ldptr; 
char *sectname; 

DESCRIPTION 

ldsseek seeks to the section specified by sectindx of the common object file 
currently associated with ldptr. 

Ldnsseek seeks to the section specified by sectname. 

ldsseek and ldnsseek return SUCCESS or FAILURE, ldsseek will fail if sectindx is 
greater than the number of sections in the object file; ldnsseek will fail if there is 
no section name corresponding with sectname. Either function will fail if there is 
no section data for the specified section or if it cannot seek to the specified sec- 
tion. 

Note that the first section has an index of one. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), ldopen(3X), ldshread(3X), ldfcn(4). 
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NAME 

ldtbindex — compute the index of a symbol table entry of a common object file 
SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <syms.h> 

#include <ldfcn.h> 

long ldtbindex (ldptr) 

LDFILE * ldptr; 

DESCRIPTION 

ldtbindex returns the (long) index of the symbol table entry at the current posi- 
tion of the common object file associated with ldptr. 

The index returned by ldtbindex may be used in subsequent calls to ldtbread( 3X). 
However, since ldtbindex returns the index of the symbol table entry that begins 
at the current position of the object file, if ldtbindex is called immediately after a 
particular symbol table entry has been read, it will return the index of the next 
entry. 

ldtbindex will fail if there are no symbols in the object file, or if the object file is 
not positioned at the beginning of a symbol table entry. 

Note that the first symbol in the symbol table has an index of zero. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), ldopen(3X), ldtbread(3X), ldtbseek(3X), ldfcn(4). 
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NAME 

ldtbread — read an indexed symbol table entry of a common object file 
SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <syms.h> 

#include <ldfcn.h> 

int ldtbread (ldptr, symindex, symbol) 

LDFILE *ldptr; 
long symindex; 

SYMENT *symbol; 

DESCRIPTION 

ldtbread reads the symbol table entry specified by symindex of the common 
object file currently associated with ldptr into the area of memory beginning at 

symbol. 

ldtbread returns SUCCESS or FAILURE, ldtbread will fail if symindex is greater 
than or equal to the number of symbols in the object file, or if it cannot read the 
specified symbol table entry. 

Note that the first symbol in the symbol table has an index of zero. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), ldopen(3X), ldtbseek(3X), ldgetname(3X), Idfcn(4). 
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NAME 

ldtbseek — seek to the symbol table of a common object file 
SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

int ldtbseek (ldptr) 

LDFILE *ldptr; 

DESCRIPTION 

ldtbseek seeks to the symbol table of the common object file currently associated 
with ldptr . 

ldtbseek returns SUCCESS or FAILURE, ldtbseek will fail if the symbol table has 
been stripped from the object file, or if it cannot seek to the symbol table. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

ldclose(3X), ldopen(3X), ldtbread(3X), ldfcn(4). 
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NAME 

libwindows — windowing terminal function library 
SYNOPSIS 

cc [flag ...] file ... — lwindows [library ...] 

int cntlfd, fd 

int chan 

int origin _x, origin_y, corner x, corner_y 

char Command 

cntlfd = openagent ( ) 

chan — New (cntlfd, originx, origin_y, cornerx, corner_y) 
chan = Newlayer (cntlfd, origin x, origin_y, corner x, corner_y) 
fd = openchan (chan) 

Runlayer (chan, command) 

Current (cntlfd, chan) 

Delete (cntlfd, chan) 

Top (cntlfd, chan) 

Bottom (cntlfd, chan) 

Move (cntlfd, chan, origin x, origin_y) 

Reshape (cntlfd, chan, origin x, origin^, corner x, corner_y) 

Exit (cntlfd) 

DESCRIPTION 

This library of routines enables a program running on a host UNIX system to 
perform windowing terminal functions (see layers( 1)). 

The openagent() routine opens the control channel of the xt(7) channel group to 
which the calling process belongs. Upon successful completion, openagentQ 
returns a file descriptor, cntlfd, that can be passed to any of the other libwindows 
routines except openchanQ and RunlayerQ. (cntlfd can also be passed to 
close( 2).) Otherwise, the value —1 is returned. 

The New() routine creates a new layer with a separate shell. The origin _x, 
origin jy, corner jc, and corner _y arguments are the coordinates of the layer rec- 
tangle. If all the coordinate arguments are 0, the user must define the layer's 
rectangle interactively. The layer appears on top of any overlapping layers. The 
layer is not made current (i.e., the keyboard is not attached to the new layer). 
Upon successful completion, New() returns the xt(7) channel number associated 
with the layer. Otherwise, the value —1 is returned. 

The NewlayerQ routine creates a new layer without executing a separate shell. 
Otherwise it is identical to New(), described above. 

The openchan() routine opens the channel argument chan which is obtained 
from the NewQ or NewlayerQ routine. Upon successful completion, open- 
chan() returns a file descriptor that can be used as input to write( 2) or close( 2). 
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Otherwise, the value — 1 is returned. 

The RunlayerQ routine runs the specified command in the layer associated with 
the channel argument chan. Any processes currently attached to this layer will 
be killed, and the new process will have the environment of the layers (1) pro- 
cess. 

The Current() routine makes the layer associated with the channel argument 
chan current (i.e., attached to the keyboard). 

The Delete() routine deletes the layer associated with the channel argument 
chan and kills all host processes associated with the layer. 

The Top() routine makes the layer associated with the channel argument chan 
appear on top of all overlapping layers. 

The Bottom() routine puts the layer associated with the channel argument chan 
under all overlapping layers. 

The MoveQ routine moves the layer associated with the channel argument chan 
from its current screen location to a new screen location at the origin point 
{origin _x, origin jy). The size and contents of the layer are maintained. 

The ReshapeQ routine reshapes the layer associated with the channel argument 
chan. The arguments origin jc, origin jy, corner _x, and corner jy are the new coor- 
dinates of the layer rectangle. If all the coordinate arguments are 0, the user is 
allowed to define the layer's rectangle interactively. 

The Exit() routine causes the layers(l) program to exit, killing all processes 
associated with it. 

RETURN VALUE 

Upon successful completion, RunlayerQ, CurrentQ, DeleteQ, Top(), BottomQ, 
MoveQ, ReshapeQ, and ExitQ return a 0, while openagentQ, NewQ, 
NewlayerQ, and openchanQ return values as described above under each rou- 
tine. If an error occurs, —1 is returned. 

FILES 

/usr /lib /lib windows. a windowing terminal function library 

NOTE 

The values of layer rectangle coordinates are dependent on the type of terminal. 
This dependency affects the routines that pass layer rectangle coordinates: 
MoveQ, NewQ, NewlayerQ, and ReshapeQ. Some terminals will expect these 
numbers to be passed as character positions (bytes); others will expect the infor- 
mation to be in pixels (bits). 

For example, for the AT&T Teletype 5620 DMD terminal, NewQ, NewlayerQ, 
and ReshapeQ take minimum values of 8 (pixels) for originjc and origin _y and 
maximum values of 792 (pixels) for corner _x and 1016 (pixels) for corner jy. In 
addition, the minimum layer size is 28 by 28 pixels and the maximum layer size 
is 784 by 1008 pixels. 

SEE ALSO 

close(2), jagent(5), write(2). 

layers(l) in the User's Reference Manual. 

xt(7) in the System Administrator's Reference Manual. 
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NAME 

logname — return login name of user 

SYNOPSIS 

char *logname( ) 

DESCRIPTION 

logname returns a pointer to the null-terminated login name; it extracts the 
LOGNAME environment variable from the user's environment. 

This routine is kept in /lib/libPW.a. 

FILES 

/etc/profile 
SEE ALSO 

getenv(3C), profile(4), environ(5). 

env(l), login(l) in the User's Reference Manual. 

CAVEATS 

The return values point to static data whose content is overwritten by each call. 
This method of determining a login name is subject to forgery. 
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NAME 

malloc, free, realloc, calloc, mallopt, mallinfo — fast main memory allocator 
SYNOPSIS 

#include <malloc.h> 

char *malloc (size) 
unsigned size; 

void free (ptr) 
char *ptr; 

char *realloc (ptr, size) 
char *ptr; 
unsigned size; 

char *calloc (nelem, elsize) 
unsigned nelem, elsize; 

int mallopt (cmd, value) 
int cmd, value; 

struct mallinfo mallinfoO 
DESCRIPTION 

malloc and free provide a simple general-purpose memory allocation package, 
which runs considerably faster than the malloc( 3C) package. It is found in the 
library // malloc ,, / and is loaded if the option lmalloc" is used with cc(l) or 

ld( 1). 

malloc returns a pointer to a block of at least size bytes suitably aligned for any 
use. 



The argument to free is a pointer to a block previously allocated by malloc; after 
free is performed this space is made available for further allocation, and its con- 
tents have been destroyed (but see mallopt below for a way to change this 
behavior). 

Undefined results will occur if the space assigned by malloc is overrun or if some 
random number is handed to free. 

Realloc changes the size of the block pointed to by ptr to size bytes and returns 
a pointer to the (possibly moved) block. The contents will be unchanged up to 
the lesser of the new and old sizes. 

Calloc allocates space for an array of nelem elements of size elsize. The space is 
initialized to zeros. 

Mallopt provides for control over the allocation algorithm. The available values 
for cmd are: 

M_MXFAST Set maxfast to value. The algorithm allocates all blocks below 
the size of maxfast in large groups and then doles them out very 
quickly. The default value for maxfast is 24. 

M_NLBLKS Set numlblks to value. The above mentioned 'Targe groups" 
each contain numlblks blocks. Numlblks must be greater than 0. 
The default value for numlblks is 1Q0. 
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M GRAIN Set grain to value. The sizes of all blocks smaller than maxfast 
are considered to be rounded up to the nearest multiple of grain. 
Grain must be greater than 0. The default value of grain is the 
smallest number of bytes which will allow alignment of any data 
type. Value will be rounded up to a multiple of the default 
when grain is set. 

MJKEEP Preserve data in a freed block until the next malloc, realloc, or 

calloc. This option is provided only for compatibility with the 
old version of malloc and is not recommended. 

These values are defined in the <malloc.h> header file. 



Mallopt may be called repeatedly, but may not be called after the first small 
block is allocated. 



Mallinfo provides 
ture: 

struct mallinfo { 
int arena; 
int ordblks; 
int smblks; 
int hblkhd; 
int hblks; 
int usmblks; 
int fsmblks; 
int uordblks; 
int fordblks; 
int keepcost; 



} 



instrumentation describing space usage. It returns the struc- 



/* total space in arena */ 

/* number of ordinary blocks */ 

/* number of small blocks */ 

/* space in holding block headers */ 
/* number of holding blocks */ 

/* space in small blocks in use */ 

/* space in free small blocks */ 

/* space in ordinary blocks in use * / 
/* space in free ordinary blocks */ 

/* space penalty if keep option * / 

/* is used */ 



This structure is defined in the <malloc.h> header file. 



Each of the allocation routines returns a pointer to space suitably aligned (after 
possible pointer coercion) for storage of any type of object. 

SEE ALSO 

brk(2), malloc(3C). 

DIAGNOSTICS 

malloc, realloc and calloc return a NULL pointer if there is not enough available 
memory. When realloc returns NULL, the block pointed to by ptr is left intact. 
If mallopt is called after any allocation or if cmd or value are invalid, non-zero is 
returned. Otherwise, it returns zero. 



WARNINGS 

This package usually uses more data space than malloc( 3C). 

The code size is also bigger than malloc( 3C). 

Note that unlike malloc( 3C), this package does not preserve the contents of a 
block when it is freed, unless the M KEEP option of mallopt is used. 
Undocumented features of malloc( 3C) have not been duplicated. 
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NAME 

plot — graphics interface subroutines 

SYNOPSIS 

openpl () 

erase () 

label (s) 
char *s; 

line (xl, yl, x2, y2) 
int xl, yl, x2, y2; 

circle (x, y, r) 
int x, y, r; 

arc (x, y, xO, yO, xl, yl) 
int x, y, xO, yO, xl, yl; 

move (x, y) 
int x, y; 

cont (x, y) 
int x, y; 

point (x, y) 
int x, y; 

linemod (s) 
char *s; 

space (xO, yO, xl, yl) 
int xO, yO, xl, yl; 

closepl () 

DESCRIPTION 

These subroutines generate graphic output in a relatively device-independent 
manner. Space must be used before any of these functions to declare the 
amount of space necessary [see plot( 4)]. Openpl must be used before any of the 
others to open the device for writing. Closepl flushes the output. 

Circle draws a circle of radius r with center at the point (x, y). 

Arc draws an arc of a circle with center at the point (x, y) between the points (xO, 
yO) and (xl, yl). 

String arguments to label and linemod are terminated by nulls and do not con- 
tain new-lines. 

See plot (4) for a description of the effect of the remaining functions. 

The library files listed below provide several flavors of these routines. 

FILES 

LIBDIR/libplot.a produces output for tplot( 1G) filters 

LIBDIR /lib300.pa for DASI 300 

LIBDIR/lib300.a for DASI 300s 
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LIBDIR/lib450.a for DASI 450 

LIBDIR /lib40 1 4 .a for TEKTRONIX 4014 

LIBDIRusually /usr/lib 

SEE ALSO 

plot(4). 

graph(lG), stat(lG), tplot(lG) in the User's Reference Manual. 

WARNINGS 

In order to compile a program containing these functions in file.c it is necessary 
to use "cc file.c — lplot". 

In order to execute it, it is necessary to use "a. out | tplot". 

The above routines use <stdio.h>, which causes them to increase the size of 
programs, not otherwise using standard I/O more than might be expected. 
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NAME 

regcmp, regex — compile and execute regular expression 
SYNOPSIS 

char *regcmp (stringl [, string2, ...], (char *)0) 
char *stringl, *string2, ...; 

char *regex (re, subject^ retO, ...]) 
char *re, *subject, *retO, 

extern char * loci; 

DESCRIPTION 

regcmp compiles a regular expression (consisting of the concatenated arguments) 
and returns a pointer to the compiled form. Malloc( 3C) is used to create space 
for the compiled form. It is the user's responsibility to free unneeded space so 
allocated. A NULL return from regcmp indicates an incorrect argument. 
regcmp (1) has been written to generally preclude the need for this routine at exe- 
cution time. 

Regex executes a compiled pattern against the subject string. Additional argu- 
ments are passed to receive values back. Regex returns NULL on failure or a 
pointer to the next unmatched character on success. A global character pointer 
loci points to where the match began, regcmp and regex were mostly bor- 
rowed from the editor, ed( 1); however, the syntax and semantics have been 
changed slightly. The following are the valid symbols and their associated 
meanings. 

[]*." These symbols retain their meaning in ed( 1). 

$ Matches the end of the string; \n matches a new-line. 

— Within brackets the minus means through. For example, [a— z] is 
equivalent to [abcd...xyz]. The — can appear as itself only if used as 
the first or last character. For example, the character class expression 
[]— ] matches the characters ] and — . 

+ A regular expression followed by + means one or more times . For 
example, [0—9]+ is equivalent to [0—9] [0—9]*. 

{m} {m,} {m,u} 

Integer values enclosed in {} indicate the number of times the preceding 
regular expression is to be applied. The value m is the minimum 
number and m is a number, less than 256, which is the maximum. If 
only m is present (e.g., {m}), it indicates the exact number of times the 
regular expression is to be applied. The value {m,} is analogous to 
{m,infinity}. The plus (+) and star (*) operations are equivalent to {l,} 
and {0,} respectively. 

( ... )$n The value of the enclosed regular expression is to be returned. The 
value will be stored in the (n+2)th argument following the subject argu- 
ment. At most ten enclosed regular expressions are allowed. Regex 
makes its assignments unconditionally. 
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(...) Parentheses are used for grouping. An operator, e.g., *, +, {}, can work 
on a single character or a regular expression enclosed in parentheses. 
For example, (a*(cb+)*)$0. 

By necessity, all the above defined symbols are special. They must, therefore, be 
escaped with a \ (backslash) to be used as themselves. 

EXAMPLES 

Example 1: 

char *cursor, *newcursor, *ptr; 

newcursor = regex((ptr = regcmp(" / '\n", (char *)0)), cursor); 
free(ptr); 

This example will match a leading new-line in the subject string pointed at by 
cursor. 

Example 2: 

char ret0[9]; 

char *newcursor, *name; 

name = regcmp("([A— Za— z][A— za— zO— 9]{0,7})$0", (char *)0); 
newcursor = regex(name, "012Testing345", retO); 

This example will match through the string "Testing3" and will return the 
address of the character after the last matched character (the "4"). The string 
"Testing3" will be copied to the character array retO. 

Example 3: 

#include "file.i" 

char *string, *newcursor; 

newcursor = regex(name, string); 

This example applies a precompiled regular expression in file.i [see regcmp( 1)] 
against string. 

These routines are kept in /lib/libPW.a. 

SEE ALSO 

regcmp(l), malloc(3C). 

ed(l) in the User's Reference Manual. 

BUGS 

The user program may run out of memory if regcmp is called iteratively without 
freeing the vectors no longer required. 
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NAME 

abort — terminate Fortran program 

SYNOPSIS 

call abort ( ) 

DESCRIPTION 

abort terminates the program which calls it, closing all open files truncated to the 
current position of the file pointer. The abort usually results in a core dump. 

DIAGNOSTICS 

When invoked, abort prints "Fortran abort routine called" on the standard error 
output. The shell prints the message "abort - core dumped" if a core dump 
results. 

SEE ALSO 

abort(3C). 

sh(l) in the User's Reference Manual. 
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NAME 

abs, iabs, dabs, cabs, zabs — Fortran absolute value 

SYNOPSIS 

integer il, i2 
real rl, r2 

double precision dpi, dp2 
complex cxl, cx2 
double complex dxl, dx2 

r2 = abs(rl) 

i2 = iabs(il) 
i2 - abs(il) 

dp2 — dabs(dpl) 
dp2 = abs(dpl) 

cx2 = cabs(cxl) 
cx2 = abs(cxl) 

dx2 = zabs(dxl) 
dx2 = abs(dxl) 

DESCRIPTION 

abs is the family of absolute value functions. labs returns the integer absolute 
value of its integer argument. Dabs returns the double-precision absolute value 
of its double-precision argument. Cabs returns the complex absolute value of its 
complex argument. Zabs returns the double-complex absolute value of its 
double-complex argument. The generic form abs returns the type of its argu- 
ment. 

SEE ALSO 

floor(3M). 
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NAME 

acos, dacos — Fortran arccosine intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
r2 = acos(rl) 

dp2 = dacos(dpl) 
dp2 = acos(dpl) 

DESCRIPTION 

acos returns the real arccosine of its real argument. Dacos returns the double- 
precision arccosine of its double-precision argument. The generic form acos may 
be used with impunity as its argument will determine the type of the returned 
value. 

SEE ALSO 

trig(3M). 
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NAME 

aimag, dimag — Fortran imaginary part of complex argument 

SYNOPSIS 

real r 

complex cxr 
double precision dp 
double complex cxd 

r = aimag(cxr) 
dp = dimag(cxd) 

DESCRIPTION 

aimag returns the imaginary part of its single-precision complex argument. 
Dimag returns the double-precision imaginary part of its double-complex argu- 
ment. 
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NAME 

aint, dint — Fortran integer part intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
r2 = aint(rl) 

dp2 = dint(dpl) 
dp2 = aint(dpl) 

DESCRIPTION 

aint returns the truncated value of its real argument in a real. Dint returns the 
truncated value of its double-precision argument as a double-precision value. 
aint may be used as a generic function name, returning either a real or double- 
precision value depending on the type of its argument. 
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NAME 

asin, dasin — Fortran arcsine intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
r2 = asin(rl) 

dp2 * dasin(dpl) 
dp2 * asin(dpl) 

DESCRIPTION 

asin returns the real arcsine of its real argument. Dasin returns the double- 
precision arcsine of its double-precision argument. The generic form asin may 
be used with impunity as it derives its type from that of its argument. 

SEE ALSO 

trig(3M). 
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NAME 

atan, datan — Fortran arctangent intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
r2 = atan(rl) 

dp2 * datan(dpl) 
dp2 = atan(dpl) 

DESCRIPTION 

atan returns the real arctangent of its real argument. Datan returns the double- 
precision arctangent of its double-precision argument. The generic form atan 
may be used with a double-precision argument returning a double-precision 
value. 

SEE ALSO 

trig(3M). 
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NAME 

atan2, datan2 — Fortran arctangent intrinsic function 

SYNOPSIS 

real rl, r2, r3 

double precision dpi, dp2, dp3 
r3 = atan2(rl, r2) 

dp3 = datan2(dpl, dp2) 
dp3 * atan2(dpl, dp2) 

DESCRIPTION 

atari! returns the arctangent of argl/arg2 as a real value. Datan 2 returns the 
double-precision arctangent of its double -precision arguments. The generic form 
atari! may be used with impunity with double -precision arguments. 

SEE ALSO 

trig(3M). 
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NAME 

bool: and, or, xor, not, lshift, rshift — Fortran Bitwise Boolean functions 

SYNOPSIS 

integer i, j, k 
real a, b, c 

k = and(i, j) 
c = or(a, b) 
j = xor(i, a) 
j = not(i) 
k = lshift(i, j) 
k = rshift(i, j) 

DESCRIPTION 

The generic intrinsic Boolean functions and, or and xor return the value of the 
binary operations on their arguments. Not is a unary operator returning the 
one's complement of its argument. Lshift and rshift return the value of the first 
argument shifted left or right, respectively, the number of times specified by the 
second (integer) argument. 

While it is recommended that Boolean functions be used only on integer data, 
these functions are generic; that is, they are defined for all data types as argu- 
ments and return values. Where required, the compiler generates appropriate 
type conversions. However, when the functions are not used with integer data, 
the results are unpredictable. 

BUGS 

The implementation of the shift functions may cause large shift values to deliver 
weird results. 

SEE ALSO 

mil(3F). 
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NAME 

conjg, dconjg — Fortran complex conjugate intrinsic function 

SYNOPSIS 

complex cxl, cx2 
double complex dxl, dx2 

cx2 = conjg(cxl) 
dx2 * dconjg(dxl) 

DESCRIPTION 

conjg returns the complex conjugate of its complex argument. Dconjg returns the 
double-complex conjugate of its double-complex argument. 
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NAME 

cos, dcos, ccos — Fortran cosine intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
complex cxl, cx2 

r2 = cos(rl) 

dp2 = dcos(dpl) 
dp2 — cos(dpl) 

cx2 = ccos(cxl) 
cx2 = cos(cxl) 

DESCRIPTION 

cos returns the real cosine of its real argument. Dcos returns the double- 
precision cosine of its double-precision argument. Ccos returns the complex 
cosine of its complex argument. The generic form cos may be used with 
impunity as its returned type is determined by that of its argument. 

SEE ALSO 

trig(3M). 
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NAME 

cosh, dcosh — Fortran hyperbolic cosine intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
r2 — cosh(rl) 

dp2 = dcosh(dpl) 
dp2 = cosh(dpl) 

DESCRIPTION 

cosh returns the real hyperbolic cosine of its real argument. Dcosh returns the 
double-precision hyperbolic cosine of its double-precision argument. The gen- 
eric form cosh may be used to return the hyperbolic cosine in the type of its 
argument. 

SEE ALSO 

sinh(3M). 
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NAME 

dim, ddim, idim — positive difference intrinsic functions 

SYNOPSIS 

integer al, a2, a3 
a3 = idim(al, a2) 

real al, a2, a3 
a3 * dim(al, a2) 

double precision al, a2, a3 
a3 = ddim(al, a2) 

DESCRIPTION 

These functions return: 

al— a2 if al > a2 
0 if al <— a2 
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NAME 

dprod — double precision product intrinsic function 

SYNOPSIS 

real al, a2 

double precision a3 

a3 * dprod(al, a2) 

DESCRIPTION 

Dprod returns the double precision product of its real arguments. 
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NAME 

exp, dexp, cexp — Fortran exponential intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
complex cxl, cx2 

r2 = exp(rl) 

dp2 = dexp(dpl) 
dp2 = exp(dpl) 

cx2 = cexp(cxl) 
cx2 = exp(cxl) 

DESCRIPTION 

exp returns the real exponential function e x of its real argument. Dexp returns 
the double-precision exponential function of its double-precision argument. 
Cexp returns the complex exponential function of its complex argument. The 
generic function exp becomes a call to dexp or cexp as required, depending on 
the type of its argument. 

SEE ALSO 

exp(3M). 
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NAME 

ftype: int, ifix, idint, real, float, sngl, dble, cmplx, dcmplx, ichar, char — explicit 
Fortran type conversion 

SYNOPSIS 

integer i, j 
real r, s 

double precision dp, dq 
complex cx 
double complex dcx 
character*! ch 

i - int(r) 
i = int(dp) 
i = int(cx) 
i = int(dcx) 
i - ifix(r) 
i = idint(dp) 

r = real(i) 
r = real(dp) 
r = real(cx) 
r = real(dcx) 
r = float(i) 
r = sngl(dp) 

dp = dble(i) 
dp = dble(r) 
dp = dble(cx) 
dp == dble(dcx) 

cx = cmplx(i) 
cx = cmplx(i, j) 
cx = cmplx(r) 
cx = cmplx(r, s) 
cx = cmplx(dp) 
cx = cmplx(dp, dq) 
cx = cmplx(dcx) 

dcx = dcmplx(i) 
dcx = dcmplx(i, j) 
dcx = dcmplx(r) 
dcx = dcmplx(r, s) 
dcx = dcmplx(dp) 
dcx — dcmplx(dp, dq) 
dcx = dcmplx(cx) 

i = ichar(ch) 
ch = char(i) 

DESCRIPTION 

These functions perform conversion from one data type to another. 

The function int converts to integer form its real, double precision, complex, or 
double complex argument. If the argument is real or double precision, int returns 
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the integer whose magnitude is the largest integer that does not exceed the mag- 
nitude of the argument and whose sign is the same as the sign of the argument 
(i.e. truncation). For complex types, the above rule is applied to the real part, 
ifix and idint convert only real and double precision arguments respectively. 

The function real converts to real form an integer , double precision, complex, or 
double complex argument. If the argument is double precision or double complex, 
as much precision is kept as is possible. If the argument is one of the complex 
types, the real part is returned, float and sngl convert only integer and double 
precision arguments respectively. 

The function dble converts any integer, real, complex, or double complex argu- 
ment to double precision form. If the argument is of a complex type, the real 
part is returned. 

The function cmplx converts its integer, real, double precision, or double complex 
argument(s) to complex form. 

The function dcmplx converts to double complex form its integer, real, double pre- 
cision, or complex argument(s). 

Either one or two arguments may be supplied to cmplx and dcmplx . If there is 
only one argument, it is taken as the real part of the complex type and an ima- 
ginary part of zero is supplied. If two arguments are supplied, the first is taken 
as the real part and the second as the imaginary part. 

The function ichar converts from a character to an integer depending on the 
character's position in the collating sequence. 

The function char returns the character in the fth position in the processor col- 
lating sequence where i is the supplied argument. 

For a processor capable of representing n characters, 
ichar(char(i)) — i for 0 < i < n, and 
char(ichar(ch)) = ch for any representable character ch. 
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NAME 

getarg — return Fortran command-line argument 

SYNOPSIS 

character*N c 
integer i 

call getarg(i, c) 

DESCRIPTION 

getarg returns the z-th command-line argument of the current process. Thus, if a 
program were invoked via 

foo argl arg2 arg3 

getarg(2, c) would return the string "arg2" in the character variable c. 

SEE ALSO 

getopt(3C). 
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NAME 

getenv — return Fortran environment variable 

SYNOPSIS 

character*N c 

call getenv(" VARIABLE NAME", c) 

DESCRIPTION 

getenv returns the character-string value of the environment variable represented 
by its first argument into the character variable of its second argument. If no 
such environment variable exists, all blanks will be returned. 

SEE ALSO 

getenv(3C), environ(5). 
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NAME 

iargc — return the number of command line arguments 

SYNOPSIS 

integer i 

i * iargc( ) 

DESCRIPTION 

The iargc function returns the number of command line arguments passed to the 
program. Thus, if a program were invoked via 

foo argl arg2 arg3 

iargc( ) would return 3. 

SEE ALSO 

getarg(3F). 
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NAME 

index — return location of Fortran substring 

SYNOPSIS 

character*Nl chi 
character*N2 ch2 
integer i 

i = index(chl, ch2) 

DESCRIPTION 

index returns the location of substring ch2 in string chi. The value returned is 
the position at which substring ch2 starts, or 0 if it is not present in string chi. 
If N2 is greater than Nl, a zero is returned. 
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NAME 

len — return length of Fortran string 

SYNOPSIS 

character*N ch 
integer i 

i = len(ch) 

DESCRIPTION 

len returns the length of string ch . 



LEN(3F) 
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NAME 

log, alog, dlog, clog — Fortran natural logarithm intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
complex cxl, cx2 

r2 = alog(rl) 
r2 - log(rl) 

dp2 = dlog(dpl) 
dp2 = log(dpl) 

cx2 = clog(cxl) 
cx2 = log(cxl) 

DESCRIPTION 

Alog returns the real natural logarithm of its real argument. Dlog returns the 
double-precision natural logarithm of its double-precision argument. Clog 
returns the complex logarithm of its complex argument. The generic function 
log becomes a call to alog , dlog, or clog depending on the type of its argument. 

SEE ALSO 

exp(3M). 
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NAME 

loglO, aloglO, dloglO — Fortran common logarithm intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 

r2 — aloglO(rl) 
r2 = loglO(rl) 

dp2 = dloglO(dpl) 
dp2 — loglO(dpl) 

DESCRIPTION 

AloglO returns the real common logarithm of its real argument. DloglO returns 
the double-precision common logarithm of its double-precision argument. The 
generic function loglO becomes a call to aloglO or dloglO depending on the type 
of its argument. 

SEE ALSO 

exp(3M). 
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NAME 

max, maxO, amaxO, maxi, amaxl, dmaxl — Fortran maximum- value functions 

SYNOPSIS 

integer i, j, k, 1 
real a, b, c, d 

double precision dpi, dp2, dp3 

1 = max(i, j, k) 
c *= max(a, b) 
dp = max(a, b, c) 
k = maxO(i, j) 
a = amaxO(i, j, k) 
i = maxl(a, b) 
d — amaxl(a, b, c) 
dp3 = dmaxl(dpl, dp2) 

DESCRIPTION 

The maximum-value functions return the largest of their arguments (of which 
there may be any number), max is the generic form which can be used for all 
data types and takes its return type from that of its arguments (which must all 
be of the same type). maxO returns the integer form of the maximum value of its 
integer arguments; amaxO, the real form of its integer arguments; maxi, the 
integer form of its real arguments; amaxl, the real form of its real arguments; 
and dmaxl, the double-precision form of its double-precision arguments. 

SEE ALSO 

min(3F). 
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NAME 

mclock — return Fortran time accounting 

SYNOPSIS 

integer i 

i = mclock( ) 

DESCRIPTION 

mclock returns time accounting information about the current process and its 
child processes. The value returned is the sum of the current process's user time 
and the user and system times of all child processes. 

SEE ALSO 

times(2), clock(3C), system(3F). 
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NAME 

mil: ior, iand, not, ieor, ishft, ishftc, ibits, btest, ibset, ibclr, mvbits — Fortran Mil- 
itary Standard functions 

SYNOPSIS 

integer i, k, 1, m, n, len 
logical b 

i = ior(m, n) 

i = iand(m, n) 

i — not(m) 

i = ieor(m, n) 

i — ishft(m, k) 

i = ishftc(m, k, len) 

i = ibits(m, k, len) 

b = btest(n, k) 

i = ibset(n, k) 

i = ibclr(n, k) 

call mvbits(m, k, len, n, 1) 

DESCRIPTION 

mil is the general name for the bit field manipulation intrinsic functions and sub- 
routines from the Fortran Military Standard (MIL-STD-1753). ior, iand, not, ieor 
— return the same results as and, or, not, xor as defined in bool( 3F). 

ishft, ishftc — m specifies the integer to be shifted, k specifies the shift count, 
k > 0 indicates a left shift, k = 0 indicates no shift, k < 0 indicates a right 
shift. In ishft, zeros are shifted in. In ishftc, the rightmost len bits are shifted 
circularly k bits. If k is greater than the machine word-size, ishftc will not shift. 

Bit fields are numbered from right to left and the rightmost bit position is zero. 
The length of the len field must be greater than zero. 

ibits — extract a subfield of len bits from m starting with bit position k and 
extending left for len bits. The result field is right justified and the remaining 
bits are set to zero. 

btest — The kth bit of argument n is tested. The value of the function is .TRUE, 
if the bit is a 1 and .FALSE, if the bit is 0. 

ibset — the result is the value of n with the kth bit set to 1 . 
ibclr — the result is the value of n with the kth bit set to 0. 

mvbits — len bits are moved beginning at position k of argument m to position 1 
of argument n. 

SEE ALSO 

bool(3F). 
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NAME 

min, minO, aminO, mini, aminl, dminl — Fortran minimum- value functions 

SYNOPSIS 

integer i, j, k, 1 
real a, b, c, d 

double precision dpi, dp2, dp3 

1 = min(i, j, k) 
c = min(a, b) 
dp = min(a, b, c) 
k * minO(i, j) 
a = aminO(i, j, k) 
i — minl(a, b) 
d = aminl(a, b, c) 
dp3 = dminl(dpl, dp2) 

DESCRIPTION 

The minimum-value functions return the minimum of their arguments (of which 
there may be any number), min is the generic form which can be used for all 
data types and takes its return type from that of its arguments (which must all 
be of the same type). minO returns the integer form of the minimum value of its 
integer arguments; aminO, the real form of its integer arguments; mini, the 
integer form of its real arguments; aminl, the real form of its real arguments; 
and dminl, the double-precision form of its double-precision arguments. 

SEE ALSO 

max(3F). 
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NAME 

mod, amod, dmod — Fortran remaindering intrinsic functions 

SYNOPSIS 

integer i, j, k 
real rl, r2, r3 

double precision dpi, dp2, dp3 
k = mod(i, j) 

r3 = amod(rl, r2) 
r3 = mod(rl, r2) 

dp3 = dmod(dpl, dp2) 
dp3 — mod(dpl, dp2) 

DESCRIPTION 

mod returns the integer remainder of its first argument divided by its second 
argument. Amod and dmod return, respectively, the real and double-precision 
whole number remainder of the integer division of their two arguments. The 
generic version mod will return the data type of its arguments. 
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NAME 

rand, irand, srand — random number generator 
SYNOPSIS 

integer iseed, i, irand 
double precision x, rand 

call srand(iseed) 
i - irand( ) 
x = rand( ) 

DESCRIPTION 

Irand generates successive pseudo-random integers in the range from 0 to 
2**15— 1. rand generates pseudo-random numbers distributed in [0, 1.0]. Srand 
uses its integer argument to re-initialize the seed for successive invocations of 
irand and rand. 

SEE ALSO 

rand(3C). 
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NAME 

round: anint, dnint, nint, idnint — Fortran nearest integer functions 

SYNOPSIS 

integer i 
real rl, r2 

double precision dpi, dp2 

r2 = anint(rl) 
i = nint(rl) 

dp2 = anint(dpl) 
dp2 = dnint(dpl) 

i = nint(dpl) 
i — idnint(dpl) 

DESCRIPTION 

Anint returns the nearest whole real number to its real argument (i.e., int(a+0.5) 
if a > 0, int(a— 0.5) otherwise). Dnint does the same for its double-precision 
argument. Nint returns the nearest integer to its real argument. Idnint is the 
double-precision version. Anint is the generic form of anint and dnint , per- 
forming the same operation and returning the data type of its argument. Nint is 
also the generic form of idnint. 
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NAME 

sign, isign, dsign — Fortran transfer-of-sign intrinsic function 

SYNOPSIS 

integer i, j, k 
real rl, r2, r3 

double precision dpi, dp2, dp3 

k = isign(i, j) 
k = sign(i, j) 

r3 = sign(rl, r2) 

dp3 * dsign(dpl, dp2) 
dp3 = sign(dpl, dp2) 

DESCRIPTION 

Isign returns the magnitude of its first argument with the sign of its second argu- 
ment. sign and dsign are its real and double-precision counterparts, respectively. 
The generic version is sign and will devolve to the appropriate type depending 
on its arguments. 
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NAME 

signal — specify Fortran action on receipt of a system signal 

SYNOPSIS 

integer i, intfc 
external intfc 

call signal(i, intfc) 

DESCRIPTION 

The argument i specifies the signal to be caught, signal allows a process to 
specify a function to be invoked upon receipt of a specific signal. The first argu- 
ment specifies which fault or exception. The second argument specifies the 
function to be invoked. 

NOTE: The interrupt processing function, intfc , does not take an argument. 

SEE ALSO 

kill(2), signal(2). 
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NAME 

sin, dsin, csin — Fortran sine intrinsic function 

SYNOPSIS 

real rl, t 2 

double precision dpi, dp2 
complex cxl, cx2 

r2 — sin(rl) 

dp2 = dsin(dpl) 
dp2 = sin(dpl) 

cx2 = csin(cxl) 
cx2 = sin(cxl) 

DESCRIPTION 

sin returns the real sine of its real argument. Dsin returns the double-precision 
sine of its double-precision argument. Csin returns the complex sine of its com- 
plex argument. The generic sin function becomes dsin or csin as required by 
argument type. 

SEE ALSO 

trig(3M). 
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NAME 

sinh, dsinh — Fortran hyperbolic sine intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
r2 - sinh(rl) 

dp2 = dsinh(dpl) 
dp2 = sinh(dpl) 

DESCRIPTION 

sinh returns the real hyperbolic sine of its real argument. Dsinh returns the / 
double-precision hyperbolic sine of its double-precision argument. The generic 
form sinh may be used to return a double-precision value when given a double- 
precision argument. 

SEE ALSO 

sinh(3M). 
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NAME 

sqrt, dsqrt, csqrt — Fortran square root intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
complex cxl, cx2 

r2 = sqrt(rl) 

dp2 = dsqrt(dpl) 
dp2 = sqrt(dpl) 

cx2 = csqrt(cxl) 
cx2 = sqrt(cxl) 

DESCRIPTION 

sqrt returns the real square root of its real argument. Dsqrt returns the double- 
precision square root of its double-precision argument. Csqrt returns the com- 
plex square root of its complex argument, sqrt, the generic form, will become 
dsqrt or csqrt as required by its argument type. 

SEE ALSO 

exp(3M). 
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NAME 

strcmp: lge, lgt, lie, lit — string comparison intrinsic functions 

SYNOPSIS 

character*N al, a2 
logical 1 

1 = lge(al, a2) 

1 = lgt(al, a2) 

1 = lle(al / a2) 

1 = llt(al, a2) 

DESCRIPTION 

These functions return .TRUE, if the inequality holds and .FALSE, otherwise. 
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NAME 

system — issue a shell command from Fortran 

SYNOPSIS 

character*N c 

call system(c) 

DESCRIPTION 

system causes its character argument to be given to sh(l) as input, as if the string 
had been typed at a terminal. The current process waits until the shell has com- 
pleted. 

SEE ALSO 

exec(2), system(3S). 

sh(l) in the User's Reference Manual. 
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NAME 

tan, dtan — Fortran tangent intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
r2 - tan(rl) 

dp2 = dtan(dpl) 
dp2 = tan(dpl) 

DESCRIPTION 

tan returns the real tangent of its real argument. Dtan returns the double- 
precision tangent of its double-precision argument. The generic tan function 
becomes dtan as required with a double-precision argument. 

SEE ALSO 

trig(3M). 
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NAME 

tanh, dtanh — Fortran hyperbolic tangent intrinsic function 

SYNOPSIS 

real rl, r2 

double precision dpi, dp2 
r2 = tanh(rl) 

dp2 = dtanh(dpl) 
dp2 = tanh(dpl) 

DESCRIPTION 

tanh returns the real hyperbolic tangent of its real argument. Dtanh returns the 
double-precision hyperbolic tangent of its double-precision argument. The gen- 
eric form tanh may be used to return a double-precision value given a double- 
precision argument. 

SEE ALSO 

sinh(3M). 
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NAME 

intro — introduction to file formats 
DESCRIPTION 

This section outlines the formats of various files. The C structure declarations 
for the file formats are given where applicable. Usually, the header files con- 
taining these structure declarations can be found in the directories /usr/include 
or /usr/include/sys. For inclusion in C language programs, however, the 
syntax #include <filename.h> or #include <sys/filename.h> should be 
used. 
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NAME 

a. out — common assembler and link editor output 
SYNOPSIS 

#include <a.out.h> 

DESCRIPTION 

The file name a.out is the default output file name from the link editor ld( 1). 
The link editor will make a.out executable if there were no errors in linking. The 
output file of the assembler as( 1), also follows the common object file format of 
the a.out file although the default file name is different. 

A common object file consists of a file header, a UNIX system header (if the file 
is link editor output), a table of section headers, relocation information, 
(optional) line numbers, a symbol table, and a string table. The order is given 
below. 

File header. 

UNIX system header. 

Section 1 header. 

Section n header. 

Section 1 data. 

Section n data. 

Section 1 relocation. 

Section n relocation. 

Section 1 line numbers. 

Section n line numbers. 

Symbol table. 

String table. 

The last three parts of an object file (line numbers, symbol table and string table) 
may be missing if the program was linked with the — s option of ld( 1) or if they 
were removed by strip ( 1). Also note that the relocation information will be 
absent after linking unless the — r option of ld{ 1) was used. The string table 
exists only if the symbol table contains symbols with names longer than eight 
characters. 

The sizes of each section (contained in the header, discussed below) are in bytes. 

When an a.out file is loaded into memory for execution, three logical segments 
are set up: the text segment, the data segment (initialized data followed by unin- 
itialized, the latter actually being initialized to all 0's), and a stack. On the 3B2 
computer the text segment starts at location 0x80800000. 

The a.out file produced by ld( 1) has the magic number 0413 in the first field of 
the UNIX system header. The headers (file header, UNIX system header, and sec- 
tion headers) are loaded at the beginning of the text segment and the text 
immediately follows the headers in the user address space. The first text address 
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will equal 0x80800000 plus the size of the headers, and will vary depending 
upon the number of section headers in the a.out file. In an a.out file with three 
sections (.text, .data, and .bss), the first text address is at 0x808000A8 on the 3B2 
computer. The text segment is not writable by the program; if other processes 
are executing the same a.out file, the processes will share a single text segment. 

The data segment starts at the next 512K boundary past the last text address. 
The first data address is determined by the following: If an a.out file were split 
into 8K chunks, one of the chunks would contain both the end of text and the 
beginning of data. When the core image is created, that chunk will appear 
twice; once at the end of text and once at the beginning of data (with some 
unused space in between). The duplicated chunk of text that appears at the 
beginning of data is never executed; it is duplicated so that the operating system 
may bring in pieces of the file in multiples of the page size without having to 
realign the beginning of the data section to a page boundary. Therefore the first 
data address is the sum of the next segment boundary past the end of text plus 
the remainder of the last text address divided by 8K. If the last text address is a 
multiple of 8K no duplication is necessary. 

On the 3B2 computer the stack begins at location 0xC0020000 and grows toward 
higher addresses. The stack is automatically extended as required. The data 
segment is extended only as requested by the brk( 2) system call. 

For relocatable files the value of a word in the text or data portions that is not a 
reference to an undefined external symbol is exactly the value that will appear in 
memory when the file is executed. If a word in the text involves a reference to 
an undefined external symbol, there will be a relocation entry for the word, the 
storage class of the symbol-table entry for the symbol will be marked as an 
"external symbol", and the value and section number of the symbol-table entry 
will be undefined. When the file is processed by the link editor and the external 
symbol becomes defined, the value of the symbol will be added to the word in 
the file. 



File Header 

The format of the filehdr header is 



struct filehdr 

( 

unsigned short 

unsigned short 

long 

long 

long 

unsigned short 
unsigned short 



fjmagic; 

f_nscns; 

f_timdat; 

f_symptr; 

fnsyms; 

f_opthdr; 

f_flags; 



/* magic number */ 

/ * number of sections * / 
/* time and date stamp */ 
/* file ptr to symtab */ 

/* # symtab entries */ 

/* sizeof(opt hdr) */ 

/* flags »/ 



UNIX System Header 

The format of the UNIX system header is 

typedef struct aouthdr 
short magic; 



/* magic number */ 
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short 


vstamp; 


/* version stamp */ 


long 


tsize; 


/* text size in bytes, padded */ 


long 


dsize; 


/* initialized data (.data) */ 


long 


bsize; 


/* uninitialized data (.bss) */ 


long 


entry; 


/* entry point */ 


long 


text_start; 


/* base of text used for this file */ 


long 
} AOUTHDR; 


data_start; 


/* base of data used for this file */ 



Section Header 

The format of the section header is 

struct scnhdr 

{ 

char 
long 
long 
long 
long 
long 
long 

unsigned short 
unsigned short 
long 

J / 

Relocation 

Object files have one relocation entry for each relocatable reference in the text or 
data. If relocation information is present, it will be in the following format: 

struct reloc 

{ 

long r_vaddr; /* (virtual) address of reference */ 

long r_symndx; /* index into symbol table */ 

ushort r_type; /* relocation type */ 

)/ 

The start of the relocation information is sjelptr from the section header. If 
there is no relocation information, sjelptr is 0. 



s_name[SYMNMLEN];/* section name */ 
sjaaddr; /* physical address */ 
s_vaddr; /* virtual address */ 
s_size; /* section size */ 
s_scnptr; /* file ptr to raw data */ 
s_relptr; /* file ptr to relocation */ 
s_lnnoptr; /* file ptr to line numbers */ 
s_nreloc; /* # reloc entries */ 
s_nlnno; /* # line number entries */ 
s_flags; /* flags */ 
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Symbol Table 

The format of each symbol in the symbol table is 

#define SYMNMLEN 8 
# define FILNMLEN 14 
#define DIMNUM 4 

struct syment 

{ 

union 

{ 

char 
struct 
{ 

long 
long 
j _n_n; 
char 
} _n; 
long 
short 

unsigned short 
char 
char 

}; 

# define n name n. n name 
#define n zeroes _n._n_n._n_zeroes 
#define n_offset _n._n_n._n_offset 

#define n_nptr _n._n_nptr[ 1 ] 

Some symbols require more information than a single entry; they are followed 
by auxiliary entries that are the same size as a symbol entry. The format fol- 
lows. 



/* all ways to get a symbol name * / 
_n_name[SYMNMLEN]; /* name of symbol */ 

_n_zeroes; /* == OL if in string table * / 
_n_offset; /* location in string table */ 

*_n_nptr[2]; /* allows overlaying */ 

n_value; /* value of symbol */ 

n_scnum; /* section number */ 

n_type; / * type and derived type * / 
n_sclass; /* storage class */ 

n_numaux; / * number of aux entries * / 
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union auxent { 
struct { 

long xtagndx; 
union { 

struct { 

unsigned short x lnno; 
unsigned short xjsize; 

} x jnsz; 
long xfsize; 

} x misc; 
union { 

struct { 

long xjnnoptr; 
long xendndx; 

} x_fcn; 
struct { 

unsigned short x_dimen[DIMNUM]; 

} x ary; 

} x_fcnary; 

unsigned short xjtvndx; 

} x_sym; 

struct { 

char x_fname[FILNMLEN]; 

} x_file; 



struct { 

long xscnlen; 
unsigned short x nreloc; 
unsigned short x nlinno; 
} x_scn; 



struct { 

long x_tvfill; 

unsigned short x_tvlen; 
unsigned short x_tvran[2]; 

} x tv; 

); 

Indexes of symbol table entries begin at zero. The start of the symbol table is 
fjymptr (from the file header) bytes from the beginning of the file. If the 
symbol table is stripped, f_symptr is 0. The string table (if one exists) begins at 
fjymptr + (fjisyms * SYMESZ) bytes from the beginning of the file. 

SEE ALSO 

as(l), cc(l), ld(l), brk(2), filehdr(4), ldfcn(4), linenum(4), reloc(4), scnhdr(4), 
syms(4). 
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NAME 

acct — per-process accounting file format 
SYNOPSIS 

#include <sys/acct.h> 

DESCRIPTION 

Files produced as a result of calling acct (2) have records in the form defined by 
<sys/acct.h>, whose contents are: 

typedef ushort comp t; /* "floating point" */ 

/* 13-bit fraction, 3-bit exponent */ 

struct acct 



char 

char 

ushort 

ushort 

devt 

time_t 

compt 

compt 

compt 

compt 

compt 

compt 

char 



acflag; 

ac_stat; 

acuid; 

ac_gid; 

actty; 

acbtime; 

ac_utime; 

acjstime; 

acetime; 

acjnem; 

acio; 

ac_rw; 

ac_comm[8]; 



/* Accounting flag */ 
/* Exit status */ 



/* Beginning time */ 

/* acctng user time in clock ticks */ 

/* acctng system time in clock ticks */ 
/* acctng elapsed time in clock ticks */ 
/ * memory usage in clicks * / 

/* chars trnsfrd by read/write */ 

/* number of block reads/writes */ 

/* command name */ 



extern struct 


acct 


acctbuf; 


extern struct 


inode 


*acctp; /* inode of accounting file */ 


#define AFORK 


01 


/ * has executed fork, but no exec * / 


#define ASU 


02 


/ * used super-user privileges * / 


#define ACCTF 


0300 


/* record type: 00 = acct */ 



In acjlag, the AFORK flag is turned on by each fork( 2) and turned off by an 
exec( 2). The ac_comm field is inherited from the parent process and is reset by 
any exec. Each time the system charges the process with a clock tick, it also 
adds to acjnem the current process size, computed as follows: 

(data size) + (text size) / (number of in-core processes using text) 

The value of acjnem / (ac_stime + acjutime) can be viewed as an approximation to 
the mean process size, as modified by text-sharing. 
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The structure tacct.h, which resides with the source files of the accounting com- 
mands, represents the total accounting format used by the various accounting 
commands: 

/* 

* total accounting (for acct period), also for day 

»/ 

struct tacct { 
uidj 
char 
float 
float 
float 
float 
long 

unsigned short 
unsigned short 
unsigned short 

}; 

SEE ALSO 

acct(2), exec(2), fork(2). 

acct(lM) in the System Administrator's Reference Manual. 
acctcom(l) in the User's Reference Manual. 

BUGS 

The acjnem value for a short-lived command gives little information about the 
actual size of the command, because acjnem may be incremented while a 
different command (e.g., the shell) is being executed by the process. 



ta_uid; /* userid */ 

ta_name[8]; /* login name */ 

ta_cpu[2]; /* cum. cpu time, p/np (mins) */ 

ta_kcore[2]; /* cum kcore-minutes, p/np */ 

ta_con[2]; /* cum. connect time, p/np, mins */ 

ta_du; /* cum. disk usage * / 

ta_pc; /* count of processes */ 

ta_sc; /* count of login sessions * / 

ta_dc; /* count of disk samples */ 

ta_fee; /* fee for special services */ 



522 




AR(4) 



AR(4) 



NAME 

ar — common archive file format 

SYNOPSIS 

#include <ar.h> 

DESCRIPTION 

The archive command ar( 1) is used to combine several files into one. Archives 
are used mainly as libraries to be searched by the link editor ld( 1). 

Each archive begins with the archive magic string. 

# define ARM AG "!<arch>\n" /* magic string */ 

#define SARMAG 8 /* length of magic string */ 



Each archive which contains common object files [see a.out( 4)] includes an 
archive symbol table. This symbol table is used by the link editor ld( 1) to deter- 
mine which archive members must be loaded during the link edit process. The 
archive symbol table (if it exists) is always the first file in the archive (but is 
never listed) and is automatically created and/or updated by ar. 

Following the archive magic string are the archive file members. Each file 
member is preceded by a file member header which is of the following format: 



#define ARFMAG ”'\n M 
struct ar hdr 



char 


ar_name[16]; 


char 


ar_date[12]; 


char 


ar_uid[6]; 


char 


ar_gid[6]; 


char 


ar_mode[8]; 


char 


ar_size[10]; 


char 


ar_fmag[2]; 



/* header trailer string * / 

/ * file member header * / 

/* '/' terminated file member name */ 
/* file member date * / 

/* file member user identification */ 

/* file member group identification */ 
/* file member mode (octal) */ 

/* file member size */ 

/* header trailer string */ 



All information in the file member headers is in printable ASCII. The numeric 
information contained in the headers is stored as decimal numbers (except for 
arjnode which is in octal). Thus, if the archive contains printable files, the 
archive itself is printable. 

The arjiame field is blank-padded and slash (/) terminated. The ar_date field is 
the modification date of the file at the time of its insertion into the archive. 
Common format archives can be moved from system to system as long as the 
portable archive command ar( 1) is used. Conversion tools such as convert ( 1) 
exist to aid in the transportation of non-common format archives to this format. 

Each archive file member begins on an even byte boundary; a newline is 
inserted between files if necessary. Nevertheless the size given reflects the 
actual size of the file exclusive of padding. 
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Notice there is no provision for empty areas in an archive file. 

If the archive symbol table exists, the first file in the archive has a zero length 
name (i.e., ar_name[0] ===== '/' ). The contents of this file are as follows: 

• The number of symbols. Length: 4 bytes. 

• The array of offsets into the archive file. Length: 4 bytes * "the number 
of symbols". 

• The name string table. Length: ar_size — (4 bytes * ("the number of 
symbols" + 1)). 

The number of symbols and the array of offsets are managed with sgetl and 
sputl. The string table contains exactly as many null terminated strings as there 
are elements in the offsets array. Each offset from the array is associated with 
the corresponding name from the string table (in order). The names in the 
string table are all the defined global symbols found in the common object files 
in the archive. Each offset is the location of the archive header for the associ- 
ated symbol. 

SEE ALSO 

ar(l), ld(l), strip(l), sputl(3X), a.out(4). 

WARNINGS 

Strip ( 1) will remove all archive symbol entries from the header. The archive 
symbol entries must be restored via the ts option of the ar( 1) command before 
the archive can be used with the link editor ld( 1). 
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NAME 

checklist — list of file systems processed by fsck and ncheck 
DESCRIPTION 

checklist resides in directory /etc and contains a list of, at most, 15 special file 
names. Each special file name is contained on a separate line and corresponds to 
a file system. Each file system will then be automatically processed by the 
fsck( 1M) command. 

FILES 

/etc/checklist 
SEE ALSO 

fsck(lM), ncheck(lM) in the System Administrator's Reference Manual. 
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NAME 

core — format of core image file 
DESCRIPTION 

The UNIX system writes out a core image of a terminated process when any of 
various errors occur. See signal( 2) for the list of reasons; the most common are 
memory violations, illegal instructions, bus errors, and user-generated quit sig- 
nals. The core image is called core and is written in the process's working direc- 
tory (provided it can be; normal access controls apply). A process with an 
effective user ID different from the real user ID will not produce a core image. 

The first section of the core image is a copy of the system's per-user data for the 
process, including the registers as they were at the time of the fault. The size of 
this section depends on the parameter usize, which is defined in 
<sys/param.h>. The remainder represents the actual contents of the user's 
core area when the core image was written. If the text segment is read-only and 
shared, or separated from data space, it is not dumped. 

The format of the information in the first section is described by the user struc- 
ture of the system, defined in <sys/user.h>. Not included in this file are the 
locations of the registers. These are outlined in <sys/reg.h>. 

SEE ALSO 

sdb(l), setuid(2), signal(2). 

crash(lM) in the System Administrator's Reference Manual . 
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NAME 

cpio — format of cpio archive 
DESCRIPTION 

The header structure, when the — c option of cpio( 1) is not used, is: 
struct { 

short hmagic, 

h_dev; 

ushort hino, 

h mode, 

huid, 

h_gid; 

short h_nlink, 

h_rdev, 
h_mtime[2], 
h_namesize, 
h_filesize[2]; 

char h_name[h_namesize rounded to word]; 

} Hdr; 

When the —c option is used, the header information is described by: 

sscanf (Chdr, "% 60 % 60 % 60 % 60 % 60 % 60 % 60 % 60 % 1 1 lo % 6o % 1 1 lo % s ", 
&Hdr.h_magic, &Hdr.h_dev, &Hdr.h_ino, &Hdr.h_mode, 
&Hdr.h_uid, &Hdr.h_gid, &Hdr.h_nlink, &Hdr.h_rdev, 
&Longtime, &Hdr.h_namesize,&Longfile,Hdr.h_name); 

Longtime and Longfile are equivalent to Hdr.hjntime and Hdr.hjilesize , respec- 
tively. The contents of each Me are recorded in an element of the array of 
varying length structures, archive, together with other items describing the file. 
Every instance of hjnagic contains the constant 070707 (octal). The items h_dev 
through hjntime have meanings explained in stat( 2). The length of the null- 
terminated path name hjiame , including the null byte, is given by hjiamesize . 

The last record of the archive always contains the name TRAILER!!!. Special files, 
directories, and the trailer are recorded with hjilesize equal to zero. 

SEE ALSO 

stat(2). 

cpio(l), find(l) in the User's Reference Manual. 
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NAME 

dir — format of directories 
SYNOPSIS 

#include <sy s/dir. h> 

DESCRIPTION 

A directory behaves exactly like an ordinary file, save that no user may write 
into a directory. The fact that a file is a directory is indicated by a bit in the flag 
word of its i-node entry [see /s(4)]. The structure of a directory entry as given in 
the include file is: 

#ifndef DIRSIZ 
# define DIRSIZ 14 
#endif 

struct direct 

{ 

ushort d_ino; 

char d_name[DIRSIZ]; 

By convention, the first two entries in each directory are for . and . .. The first is 
an entry for the directory itself. The second is for the parent directory. The 
meaning of .. is modified for the root directory of the master file system; there is 
no parent, so .. has the same meaning as .. 

SEE ALSO 

fs(4). 
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NAME 

dirent — file system independent directory entry 
SYNOPSIS 

#include <sys/dirent.h> 

#include <sys/types.h> 

DESCRIPTION 

Different file system types may have different directory entries. The dirent struc- 
ture defines a file system independent directory entry, which contains informa- 
tion common to directory entries in different file system types. A set of these 
structures is returned by the getdents( 2) system call. 



The dirent structure is defined below. 




struct dirent { 




long 


d ino; 


offj 


doff; 


unsigned short 


d_reclen; 


char 


d_name[l]; 



The djno is a number which is unique for each file in the file system. The field 
d_off is the offset of that directory entry in the actual file system directory. The 
field djiame is the beginning of the character array giving the name of the direc- 
tory entry. This name is null terminated and may have at most MAXNAMLEN 
characters. This results in file system independent directory entries being vari- 
able length entities. The value of djeclen is the record length of this entry. 
This length is defined to be the number of bytes between the current entry and 
the next one, so that it will always result in the next entry being on a long 
boundary. 

FILES 

/usr /include /sys /dirent.h 

SEE ALSO 

getdents(2). 
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NAME 

.edt_swapp — software application file 
DESCRIPTION 

The .edtjwapp file is read by filledt(8) on its second pass during the self- 
configuration process to rename specified Equipped Device Table (EDT) entries. 
The file has the following format: 

SLOT SWNAME HWNAME 



FF 

The number in the slot field specifies the entry in the EDT to be updated. The 
SWNAME column contains the new name which will be associated with this 
board. The HWNAME field contains the name which the board was associated 
with generically. The last line contains 'FF' for the slot number to signal the end 
of the data to the firmware. This file can be displayed by the editsa -l command. 

WARNINGS 

This file is not to be edited directly. Updates to it must be done through editsa. 
SEE ALSO 

editsa(lM), filledt(8) in the System Administrator's Reference Manual. 
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NAME 

filehdr — file header for common object files 
SYNOPSIS 

#include < filehdr. h> 

DESCRIPTION 

Every common object file begins with a 20 -byte header. The following C struct 
declaration is used: 

struct filehdr 

{ 

unsigned short 
unsigned short 
long 
long 
long 

unsigned short 
unsigned short 

); 

F_symptr is the byte offset into the file at which the symbol table can be found. 
Its value can be used as the offset in fseek( 3S) to position an I/O stream to the 
symbol table. The UNIX system optional header is 28-bytes. The valid magic 
numbers are given below: 

#define FBOMAGIC 0560 /* 3B2 and 3B5 computers */ 

#define N3BMAGIC 0550 /* 3B20 computer */ 

# define NTVMAGIC 0551 /* 3B20 computer */ 

#define VAXWRMAGIC 0570 /* VAX writable text segments */ 

#define VAXROMAGIC 0575 /* VAX read only sharable 

text segments */ 

The value in fjimdat is obtained from the time (2) system call. Flag bits 
currently defined are: 

#define F_RELFLG 0000001 /* relocation entries stripped */ 

#define F EXEC 0000002 /* file is executable */ 

# define F LNNO 0000004 /* line numbers stripped */ 

#define F LSYMS 0000010 /* local symbols stripped */ 

#define F_MINMAL 0000020 /* minimal object file */ 

#define F UPDATE 0000040 /* update file, ogen produced */ 

#define F SWABD 0000100 /* file is "pre-swabbed" */ 

# define F AR16WR 0000200 /* 16-bit DEC host */ 

#define F_AR32WR 0000400 /* 32-bit DEC host */ 

# define F_AR32W 0001000 /* non-DEC host */ 

#define F PATCH 0002000 /* "patch” list in opt hdr */ 

#define F_BM32ID 0160000 /* WE32000 family ID field */ 

#define F BM32B 0020000 /* file contains WE 32100 code */ 

#define F BM32MAU 0040000 /* file reqs MAU to execute */ 

#define F BM32RST 0010000 /* this object file contains restore 

work around [3B5/3B2 only] */ 



f_magic ; /* magic number * / 

f_nscns ; / * number of sections * / 

fjimdat ; /* time & date stamp */ 
f_symptr ; /* file ptr to symtab */ 
f_nsyms ; /* # symtab entries */ 
f_opthdr ; /* sizeof(opt hdr) */ 
f_flags ; /* flags */ 
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SEE ALSO 

time(2), fseek(3S), a.out(4). 
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NAME 

fs: file system — format of system volume 
SYNOPSIS 

#include <sys/filsys.h> 

#include <sys/types.h> 

#include <sys/param.h> 

DESCRIPTION 

Every file system storage volume has a common format for certain vital informa- 
tion. Every such volume is divided into a certain number of 512-byte long sec- 
tors. Sector 0 is unused and is available to contain a bootstrap program or other 
information. 

Sector 1 is the super-block. The format of a super-block is: 



struct 

{ 


filsys 

ushort 


sjsize; 


/ * size in blocks of i-list * / 




daddrt 


sfsize; 


/ * size in blocks of entire volume * / 




short 


s_nfree; 


/* number of addresses in s_free */ 




daddrt 


s_free[NICFREE]; 


/* free block list */ 




short 


s_ninode; 


/* number of i-nodes in s_inode */ 




ushort 


s_inode[NICINOD]; 


/* free i-node list */ 




char 


s_flock; 


/* lock during free list manipulation * / 




char 


silock; 


/* lock during i-list manipulation * / 




char 


s_fmod; 


/ * super block modified flag * / 




char 


sronly; 


/* mounted read-only flag */ 




time_t 


s_time; 


/* last super block update */ 




short 


s_dinfo[4]; 


/ * device information * / 




daddrt 


stfree; 


/* total free blocks* / 




ushort 


s_tinode; 


/* total free i-nodes */ 




char 


s_fname[6]; 


/* file system name */ 




char 


s fpack[6]; 


/* file system pack name */ 




long 


s_fill[12]; 


/* ADJUST to make sizeof filsys 




long 


s_state; 


be 512*/ 

/* file system state */ 




long 


s_magic; 


/* magic number to denote new 


}; 


long 


s_type; 


file system */ 

/* type of new file system */ 


#define 


FsMAGIC 


0xfdl87e20 


/* sjnagic number */ 


#define 


Fslb 


1 


/* 512-byte block */ 


#define 


Fs2b 


2 


/* 1024-byte block */ 


#define 


FsOKAY 


0x7c269d38 


/* s_state: clean */ 


#define 


FsACTIVE 


0x5e72d81a 


/* s_state: active */ 


#define 


FsBAD 


0xcb096f43 


/* s_state: bad root */ 


#define 


FsBADBLK 


0xbadbcl4b 


/* s_state: bad block corrupted it */ 
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Sjype indicates the file system type. Currently, two types of file systems are 
supported: the original 512-byte logical block and the improved 1024-byte log- 
ical block. Sjnagic is used to distinguish the original 512-byte oriented file sys- 
tems from the newer file systems. If this field is not equal to the magic number, 
fsMAGIC, the type is assumed to be fslb, otherwise the sjype field is used. In 
the following description, a block is then determined by the type. For the ori- 
ginal 512-byte oriented file system, a block is 512-bytes. For the 1024-byte 
oriented file system, a block is 1024-bytes or two sectors. The operating system 
takes care of all conversions from logical block numbers to physical sector 
numbers. 

S_state indicates the state of the file system. A cleanly unmounted, not damaged 
file system is indicated by the FsOKAY state. After a file system has been 
mounted for update, the state changes to FsACTIVE. A special case is used for 
the root file system. If the root file system appears damaged at boot time, it is 
mounted but marked FsBAD. Lastly, after a file system has been unmounted, 
the state reverts to FsOKAY. 

SJsize is the address of the first data block after the i-list; the i-list starts just 
after the super-block, namely in block 2; thus the i-list is sJsize— 2 blocks long. 
SJsize is the first block not potentially available for allocation to a file. These 
numbers are used by the system to check for bad block numbers; if an "impos- 
sible" block number is allocated from the free list or is freed, a diagnostic is 
written on the on-line console. Moreover, the free array is cleared, so as to 
prevent further allocation from a presumably corrupted free list. 

The free list for each volume is maintained as follows. The sjree array contains, 
in sjree[ 1], ..., sjree[s_nfree— 1], up to 49 numbers of free blocks. SJree[ 0] is 
the block number of the head of a chain of blocks constituting the free list. The 
first long in each free-chain block is the number (up to 50) of free-block 
numbers listed in the next 50 longs of this chain member. The first of these 50 
blocks is the link to the next member of the chain. To allocate a block: decre- 
ment sjifree, and the new block is sjree[s_nfree]. If the new block number is 0, 
there are no blocks left, so give an error. If sjifree became 0, read in the block 
named by the new block number, replace sjifree by its first word, and copy the 
block numbers in the next 50 longs into the sjree array. To free a block, check 
if sjifree is 50; if so, copy sjifree and the sjree array into it, write it out, and 
set sjifree to 0. In any event set sjree[sjifree] to the freed block's number and 
increment sjifree. 

Sjfree is the total free blocks available in the file system. 

Sjiinode is the number of free i-numbers in the sjnode array. To allocate an i- 
node: if sjiinode is greater than 0, decrement it and return sJnode[sjiinode]. If 
it was 0, read the i-list and place the numbers of all free i-nodes (up to 100) into 
the sjnode array, then try again. To free an i-node, provided sjiinode is less 
than 100, place its number into sJnode[sjiinode] and increment sjiinode. If 
sjiinode is already 100, do not bother to enter the freed i-node into any table. 
This list of i-nodes is only to speed up the allocation process; the information as 
to whether the i-node is really free or not is maintained in the i-node itself. 

Sjinode is the total free i-nodes available in the file system. 
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S Jlock and sjlock are flags maintained in the core copy of the file system while 
it is mounted and their values on disk are immaterial. The value of sjmod on 
disk is likewise immaterial; it is used as a flag to indicate that the super-block 
has changed and should be copied to the disk during the next periodic update of 
file system information. 

S_ronly is a read-only flag to indicate write-protection. 

S_time is the last time the super-block of the file system was changed, and is the 
number of seconds that have elapsed since 00:00 Jan. 1, 1970 (GMT). During a 
reboot, the sjime of the super-block for the root file system is used to set the 
system's idea of the time. 

SJname is the name of the file system and sjpack is the name of the pack. 

I-numbers begin at 1, and the storage for i-nodes begins in block 2. Also, i- 
nodes are 64 bytes long. I-node 1 is reserved for future use. I-node 2 is 
reserved for the root directory of the file system, but no other i-number has a 
built-in meaning. Each i-node represents one file. For the format of an i-node 
and its flags, see inode ( 4). 

SEE ALSO 

mount(2), inode(4). 

fsck(lM), fsdb(lM), mkfs(lM) in the System Administrator's Reference Manual. 
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NAME 

fspec — format specification in text files 
DESCRIPTION 

It is sometimes convenient to maintain text files on the UNIX system with non- 
standard tabs, (i.e., tabs which are not set at every eighth column). Such files 
must generally be converted to a standard format, frequently by replacing all 
tabs with the appropriate number of spaces, before they can be processed by 
UNIX system commands. A format specification occurring in the first line of a 
text file specifies how tabs are to be expanded in the remainder of the file. 

A format specification consists of a sequence of parameters separated by blanks 
and surrounded by the brackets <: and :>. Each parameter consists of a 
keyletter, possibly followed immediately by a value. The following parameters 
are recognized: 

t tabs The t parameter specifies the tab settings for the file. The value of 

tabs must be one of the following: 

1. a list of column numbers separated by commas, indicating tabs 
set at the specified columns; 

2. a — followed immediately by an integer n, indicating tabs at 
intervals of n columns; 

3. a — followed by the name of a "canned" tab specification. 

Standard tabs are specified by t— 8, or equivalently, tl / 9 / 17,25 / etc. 
The canned tabs which are recognized are defined by the tabs( 1) 
command. 

The s parameter specifies a maximum line size. The value of size 
must be an integer. Size checking is performed after tabs have been 
expanded, but before the margin is prepended. 

The m parameter specifies a number of spaces to be prepended to 
each line. The value of margin must be an integer. 

The d parameter takes no value. Its presence indicates that the line 
containing the format specification is to be deleted from the con- 
verted file. 

e The e parameter takes no value. Its presence indicates that the 

current format is to prevail only until another format specification is 
encountered in the file. 

Default values, which are assumed for parameters not supplied, are t— 8 and mO. 
If the s parameter is not specified, no size checking is performed. If the first line 
of a file does not contain a format specification, the above defaults are assumed 
for the entire file. The following is an example of a line containing a format 
specification: 

* <:t5,10,15 s72:> * 



s size 

mmargin 

d 
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If a format specification can be disguised as a comment, it is not necessary to 
code the d parameter. 

SEE ALSO 

ed(l), newform(l), tabs(l) in the User's Reference Manual. 
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NAME 

fstab — file-system-table 



DESCRIPTION 

The /etc/fstab file contains information about file systems for use by mount 
(1M) and mountall(lM). Each entry in /etc/fstab has the following format: 



column 1 block special file name of file system or advertised 
remote resource 

column 2 mount-point directory 

column 3 r" if to be mounted read-only; d[r]" if remote 

column 4 (optional) file system type string 

column 5+ ignored 

White-space separates columns. Lines beginning with "# " are comments. 
Empty lines are ignored. 

A file-system- table might read: 

/dev/dsk/cld0s2 /usr S51K 
/dev/dsk/cldls2 /usr/src -r 
adv_resource /mnt -d 



FILES 

/etc/fstab 
SEE ALSO 

mount(lM), mountall(lM), rmountall(lM) in the System Administrator's Reference 
Manual. 
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NAME 

gettydefs — speed and terminal settings used by getty 
DESCRIPTION 

The /etc/gettydefs file contains information used by getty (1M) to set up the 
speed and terminal settings for a line. It supplies information on what the login 
prompt should look like. It also supplies the speed to try next if the user indi- 
cates the current speed is not correct by typing a <loreak> character. 

Each entry in /etc/gettydefs has the following format: 

label# initial-flags # final-flags # login-prompt #next-label 

Each entry is followed by a blank line. The various fields can contain quoted 
characters of the form \b, \n, \c, etc., as well as \nnn, where nnn is the octal 
value of the desired character. The various fields are: 

This is the string against which getty tries to match its second 
argument. It is often the speed, such as 1200, at which the ter- 
minal is supposed to run, but it need not be (see below). 

These flags are the initial ioctl( 2) settings to which the terminal is 
to be set if a terminal type is not specified to getty. The flags 
that getty understands are the same as the ones listed in 
/usr/include/sys/termio.h [see termio(7)\. Normally only the 
speed flag is required in the initial- flags. Getty automatically sets 
the terminal to raw input mode and takes care of most of the 
other flags. The initial-flag settings remain in effect until getty 
executes login(l). 

These flags take the same values as the initial-flags and are set 
just prior to getty executes login. The speed flag is again 
required. The composite flag SANE takes care of most of the 
other flags that need to be set so that the processor and terminal 
are communicating in a rational fashion. The other two com- 
monly specified final-flags are TAB3, so that tabs are sent to the 
terminal as spaces, and HUPCL, so that the line is hung up on the 
final close. 

login-prompt This entire field is printed as the login-prompt. Unlike the above 
fields where white space is ignored (a space, tab or new-line), 
they are included in the login-prompt field. 

next-label If this entry does not specify the desired speed, indicated by the 
user typing a <break> character, then getty will search for the 
entry with next-label as its label field and set up the terminal for 
those settings. Usually, a series of speeds are linked together in 
this fashion, into a closed set; For instance, 2400 linked to 1200, 
which in turn is linked to 300, which finally is linked to 2400. 

If getty is called without a second argument, then the first entry of 
/etc/gettydefs is used, thus making the first entry of /etc/gettydefs the default 
entry. It is also used if getty can not find the specified label. If /etc/gettydefs 
itself is missing, there is one entry built into the command which will bring up a 
terminal at 300 baud. 



label 

initial-flags 
final -flags 
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It is strongly recommended that after making or modifying /etc/gettydefs, it be 
run through getty with the check option to be sure there are no errors. 

FILES 

/etc/gettydefs 

SEE ALSO 

ioctl(2). 

getty(lM), termio(7) in the System Administrator's Reference Manual. 
login(l) in the User's Reference Manual. 
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NAME 

gp s — graphical primitive string, format of graphical files 
DESCRIPTION 

GPS is a format used to store graphical data. Several routines have been 

developed to edit and display GPS files on various devices. Also, higher level 

graphics programs such as plot [in stat(lG)] and vtoc [in foc(lG)] produce GPS 

format output files. 

A GPS is composed of five types of graphical data or primitives. 

GPS PRIMITIVES 

lines The lines primitive has a variable number of points from which zero 
or more connected line segments are produced. The first point given 
produces a move to that location. (A move is a relocation of the 
graphic cursor without drawing.) Successive points produce line seg- 
ments from the previous point. Parameters are available to set color, 
weight, and style (see below). 

arc The arc primitive has a variable number of points to which a curve is 

fit. The first point produces a move to that point. If only two points 
are included, a line connecting the points will result; if three points a 
circular arc through the points is drawn; and if more than three, lines 
connect the points. (In the future, a spline will be fit to the points if 
they number greater than three.) Parameters are available to set color, 
weight, and style. 

text The text primitive draws characters. It requires a single point which 

locates the center of the first character to be drawn. Parameters are 
color, font, textsize, and textangle. 

hardware The hardware primitive draws hardware characters or gives control 
commands to a hardware device. A single point locates the begin- 
ning location of the hardware string. 

comment A comment is an integer string that is included in a GPS file but 
causes nothing to be displayed. All GPS files begin with a comment 
of zero length. 

GPS PARAMETERS 

color Color is an integer value set for arc, lines, and text primitives. 

weight Weight is an integer value set for arc and lines primitives to indicate 
line thickness. The value 0 is narrow weight, 1 is bold, and 2 is 
medium weight. 

style Style is an integer value set for lines and arc primitives to give one of 
the five different line styles that can be drawn on TEKTRONIX 4010 
series storage tubes. They are: 

0 solid 

1 dotted 

2 dot dashed 

3 dashed 

4 long dashed 
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An integer value set for text primitives to designate the text font to be 
used in drawing a character string. (Currently font is expressed as a 
four-bit weight value followed by a four-bit style value.) 

Textsize is an integer value used in text primitives to express the size 
of the characters to be drawn. Textsize represents the height of char- 
acters in absolute universe -units and is stored at one-fifth this value in 
the size-orientation (so) word (see below). 

T extangle is a signed integer value used in text primitives to express 
rotation of the character string around the beginning point. T extangle 
is expressed in degrees from the positive x-axis and can be a positive 
or negative value. It is stored in the size-orientation (so) word as a 
value 256/360 of it's absolute value. 

ORGANIZATION 

GPS primitives are organized internally as follows: 

lines cw points sw 

arc cw points sw 

text cw point sw so [string] 

hardware cw point [string] 

comment cw [string] 

cw Cw is the control word and begins all primitives. It consists of four 

bits that contain a primitive-type code and twelve bits that contain 
the word-count for that primitive. 

point(s) Point(s) is one or more pairs of integer coordinates. Text and 
hardware primitives only require a single point. Point(s) are values 
within a Cartesian plane or universe having 64K (— 32K to +32K) 
points on each axis. 

sw Sw is the style-word and is used in lines, arc, and text primitives. For 

all three, eight bits contain color information. In arc and lines eight 
bits are divided as four bits weight and four bits style. In the text 
primitive eight bits of sw contain the font. 

so So is the size-orientation word used in text primitives. Eight bits con- 

tain text size and eight bits contain text rotation. 

string String is a null-terminated character string. If the string does not end 
on a word boundary, an additional null is added to the GPS file to 
insure word-boundary alignment. 

SEE ALSO 

graphics(lG), stat(lG), toc(lG) in the User's Reference Manual. 



font 

textsize 



textangle 
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NAME 

group — group file 
DESCRIPTION 

group contains for each group the following information: 

group name 
encrypted password 
numerical group ID 

comma-separated list of all users allowed in the group 

This is an ASCII file. The fields are separated by colons; each group is separated 
from the next by a new-line. If the password field is null, no password is 
demanded. 

This file resides in directory /etc. Because of the encrypted passwords, it can 
and does have general read permission and can be used, for example, to map 
numerical group ID's to names. 

FILES 

/etc/group 

SEE ALSO 

passwd(4). 

passwd(l) in the User's Reference Manual. 

newgrp(lM) in the System Administrator's Reference Manual . 
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NAME 

inittab — script for the init process 
DESCRIPTION 

The inittab file supplies the script to init' s role as a general process dispatcher. 
The process that constitutes the majority of init' s process dispatching activities is 
the line process /etc/getty that initiates individual terminal lines. Other 
processes typically dispatched by init are daemons and the shell. 

The inittab file is composed of entries that are position dependent and have the 
following format: 

id:rstate:action:process 

Each entry is delimited by a newline, however, a backslash (\) preceding a new- 
line indicates a continuation of the entry. Up to 512 characters per entry are 
permitted. Comments may be inserted in the process field using the sh( 1) con- 
vention for comments. Comments for lines that spawn gettys are displayed by 
the who(l) command. It is expected that they will contain some information 
about the line such as the location. There are no limits (other than maximum 
entry size) imposed on the number of entries within the inittab file. The entry 
fields are: 

id This is one or two characters used to uniquely identify an entry. 

rstate This defines the run-level in which this entry is to be processed. Run- 

levels effectively correspond to a configuration of processes in the 
system. That is, each process spawned by init is assigned a run-level 
or run-levels in which it is allowed to exist. The run-levels are 
represented by a number ranging from 0 through 6. As an example, if 
the system is in run-level 1 , only those entries having a 1 in the rstate 
field will be processed. When init is requested to change run-levels, all 
processes which do not have an entry in the rstate field for the target 
run-level will be sent the warning signal (SIGTERM) and allowed a 20- 
second grace period before being forcibly terminated by a kill signal 
(SIGKILL). The rstate field can define multiple run-levels for a process 
by selecting more than one run-level in any combination from 0—6. If 
no run-level is specified, then the process is assumed to be valid at all 
run-levels 0—6. There are three other values, a, b and c, which can 
appear in the rstate field, even though they are not true run-levels. 
Entries which have these characters in the rstate field are processed 
only when the telinit [see init( 1M)] process requests them to be run 
(regardless of the current run-level of the system). They differ from 
run-levels in that init can never enter run-level a, b or c. Also, a 
request for the execution of any of these processes does not change the 
current run-level. Furthermore, a process started by an a, b or c com- 
mand is not killed when init changes levels. They are only killed if 
their line in /etc/inittab is marked off in the action field, their line is 
deleted entirely from /etc/inittab, or init goes into the SINGLE USER 
state. 

action Key words in this field tell init how to treat the process specified in the 
process field. The actions recognized by init are as follows: 
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respawn 

wait 

once 

boot 

bootwait 

powerfail 

powerwait 

off 

ondemand 

initdefault 



If the process does not exist then start the process, do not 
wait for its termination (continue scanning the inittab file), 
and when it dies restart the process. If the process 
currently exists then do nothing and continue scanning 
the inittab file. 

Upon init's entering the run-level that matches the entry's 
rstate, start the process and wait for its termination. All 
subsequent reads of the inittab file while init is in the 
same run-level will cause init to ignore this entry. 

Upon init's entering a run-level that matches the entry's 
rstate, start the process, do not wait for its termination. 
When it dies, do not restart the process. If upon entering 
a new run-level , where the process is still running from a 
previous run-level change, the program will not be res- 
tarted. 

The entry is to be processed only at init's boot- time read 
of the inittab file. Init is to start the process, not wait for 
its termination; and when it dies, not restart the process. 
In order for this instruction to be meaningful, the rstate 
should be the default or it must match init's run-level at 
boot time. This action is useful for an initialization func- 
tion following a hardware reboot of the system. 

The entry is to be processed the first time init goes from 
single-user to multi-user state after the system is booted. 
(If initdefault is set to 2, the process will run right after 
the boot.) Init starts the process, waits for its termination 
and, when it dies, does not restart the process. 

Execute the process associated with this entry only when 
init receives a power fail signal [SIGPWR see signal ( 2)]. 

Execute the process associated with this entry only when 
init receives a power fail signal (SIGPWR) and wait until it 
terminates before continuing any processing of inittab. 

If the process associated with this entry is currently run- 
ning, send the warning signal (SIGTERM) and wait 20 
seconds before forcibly terminating the process via the 
kill signal (SIGKILL). If the process is nonexistent, ignore 
the entry. 

This instruction is really a synonym for the respawn 
action. It is functionally identical to respawn but is given 
a different keyword in order to divorce its association 
with run-levels. This is used only with the a, b or c 
values described in the rstate field. 

An entry with this action is only scanned when init ini- 
tially invoked. Init uses this entry, if it exists, to deter- 
mine which run-level to enter initially. It does this by 
taking the highest run-level specified in the rstate field 
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and using that as its initial state. If the rstate field is 
empty, this is interpreted as 0123456 and so init will enter 
run-level 6. Additionally, if init does not find an initde- 
fault entry in /etc/inittab, then it will request an initial 
run-level from the user at reboot time. 

sysinit Entries of this type are executed before init tries to access 
the console (i.e., before the Console Login: prompt). It is 
expected that this entry will be only used to initialize 
devices on which init might try to ask the run-level ques- 
tion. These entries are executed and waited for before 
continuing. 

process This is a sh command to be executed. The entire process field is 
prefixed with exec and passed to a forked sh as sh — c 'exec command'. 
For this reason, any legal sh syntax can appear in the process field. 
Comments can be inserted with the ; # comment syntax. 

FILES 

/etc/inittab 
SEE ALSO 

exec(2), open(2), signal(2). 

getty(lM), init(lM) in the System Administrator's Reference Manual. 

sh(l), who(l) in the User's Reference Manual 
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NAME 

inode — format of an i-node 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/ino.h> 

DESCRIPTION 

An i-node for a plain file or directory in a file system has the following structure 

defined by <sys/ino.h>. 

/* Inode structure as it appears on a disk block. */ 
struct dinode 
{ 

ushort di mode; /* mode and type of file */ 

short di nlink; /* number of links to file * / 

ushort di_uid; /* owner's user id */ 

ushort di_gid; /* owner's group id */ 

off_t di_size; / * number of bytes in file * / 

char di_addr[40]; /* disk block addresses */ 

time_t di_atime; /* time last accessed */ 

time_t di_mtime; /* time last modified */ 

time_t di_ctime; /* time of last file status change * / 

)/ 

/* 

* the 40 address bytes: 

* 39 used; 13 addresses 

* of 3 bytes each. 

v 

For the meaning of the defined types offj and timej see types(5). 

SEE ALSO 

stat(2), fs(4), types(5). 
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NAME 

issue — issue identification file 
DESCRIPTION 

The file /etc/issue contains the issue or project identification to be printed as a 
login prompt. This is an ASCII file which is read by program getty and then 
written to any terminal spawned or respawned from the lines file. 

FILES 

/etc/issue 
SEE ALSO 

login(l) in the User's Reference Manual. 
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NAME 

ldfcn — common object file access routines 
SYNOPSIS 

#include <stdio.h> 

#include <filehdr.h> 

#include <ldfcn.h> 

DESCRIPTION 

The common object file access routines are a collection of functions for reading 
common object files and archives containing common object files. Although the 
calling program must know the detailed structure of the parts of the object file 
that it processes, the routines effectively insulate the calling program from 
knowledge of the overall structure of the object file. 

The interface between the calling program and the object file access routines is 
based on the defined type LDFILE, defined as struct ldfile, declared in the 
header file ldfcn.h. The primary purpose of this structure is to provide uniform 
access to both simple object files and to object files that are members of an 
archive file. 

The function ldopen( 3X) allocates and initializes the LDFILE structure and returns 
a pointer to the structure to the calling program. The fields of the LDFILE struc- 
ture may be accessed individually through macros defined in ldfcn.h and con- 
tain the following information: 

LDFILE *ldptr; 

TYPE(ldptr) The file magic number used to distinguish between archive 
members and simple object files. 

IOPTR(ldptr) The file pointer returned by fopen and used by the standard 
input/output functions. 

OFFSET(ldptr) The file address of the beginning of the object file; the offset is 
non-zero if the object file is a member of an archive file. 

HEADER(ldptr) The file header structure of the object file. 

The object file access functions themselves may be divided into four categories: 

(1) functions that open or close an object file 

ldopen( 3X) and ldaopen[ see ldopen( 3X)] 
open a common object file 
ldclose( 3X) and ldaclose[ see ldclose( 3X)] 
close a common object file 

(2) functions that read header or symbol table information 

ldahread( 3X) 

read the archive header of a member of an archive file 
ldfhread( 3X) 

read the file header of a common object file 
ldshread(3X) and ldnshread[ see ldshread( 3X)] 

read a section header of a common object file 



549 




LDFCN(4) 



LDFCN(4) 



ldtbread( 3X) 

read a symbol table entry of a common object file 
ldgetname( 3X) 

retrieve a symbol name from a symbol table entry or 
from the string table 

(3) functions that position an object file at (seek to) the start of the sec- 
tion, relocation, or line number information for a particular section. 

ldohseek( 3X) 

seek to the optional file header of a common object file 
ldsseek( 3X) and ldnsseek[ see ldsseek( 3X)] 

seek to a section of a common object file 
ldrseek( 3X) and ldnrseek[ see ldrseek( 3X)] 

seek to the relocation information for a section of a 
common object file 

ldlseek( 3X) and ldnlseek[ see ldlseek( 3X)] 

seek to the line number information for a section of a 
common object file 
ldtbseek( 3X) 

seek to the symbol table of a common object file 

(4) the function ldtbindex( 3X) which returns the index of a particular 
common object file symbol table entry. 

These functions are described in detail on their respective manual pages. 

All the functions except ldopen( 3X), ldgetname( 3X), ldtbindex( 3X) return either 
SUCCESS or FAILURE, both constants defined in ldfcn.h. Ldopen( 3X) and 
ldaopen[( see ldopen( 3X)] both return pointers to an LDFILE structure. 

Additional access to an object file is provided through a set of macros defined in 
ldfcn.h. These macros parallel the standard input/output file reading and mani- 
pulating functions, translating a reference of the LDFILE structure into a refer- 
ence to its file descriptor field. 

The following macros are provided: 

GETC(ldptr) 

FGETC(ldptr) 

GETW(ldptr) 

UNGETC(c, ldptr) 

FGETS(s, n, ldptr) 

FREAD((char *) ptr, sizeof (*ptr), nitems, ldptr) 

FSEEK(ldptr, offset, ptrname) 

FTELL(ldptr) 

REWIND(ldptr) 

FEOF(ldptr) 

FERROR(ldptr) 

FILENO(ldptr) 

SETBUF(ldptr, buf) 

STROFFSET (ldptr) 
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The STROFFSET macro calculates the address of the string table. See the manual 
entries for the corresponding standard input/output library functions for details 
on the use of the rest of the macros. 

The program must be loaded with the object file access routine library libld.a. 
SEE ALSO 

fseek(3S), ldahread(3X), ldclose(3X), ldgetname(3X), ldfhread(3X), ldlread(3X), 
ldlseek(3X), ldohseek(3X), ldopen(3X), ldrseek(3X), ldlseek(3X), ldshread(3X), 
ldtbindex(3X), ldtbread(3X), ldtbseek(3X), stdio(3S), intro(5). 

WARNING 

The macro FSEEK defined in the header file ldfcn.h translates into a call to the 
standard input/output function fseek( 3S). FSEEK should not be used to seek 
from the end of an archive file since the end of an archive file may not be the 
same as the end of one of its object file members! 
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NAME 

limits — file header for implementation-specific constants 
SYNOPSIS 

#include <limits.h> 

DESCRIPTION 

The header file <limits.h> is a list of magnitude limitations imposed by a 
specific implementation of the operating system. All values are specified in 
decimal. 

#define ARG_MAX 5120 /* max length of arguments to exec */ 

#def ine CHAR_BIT 8 /* # of bits in a "char" */ 

#define CHAR_MAX 127 /* max integer value of a "char" */ 

#define CHAR_MIN -128 /* min integer value of a "char" */ 

#define CHILD_MAX 25 /* max # of processes per user id */ 

#define CLK_TCK 100 /* # of clock ticks per second */ 

#define DBL_DIG 16 /* digits of precision of a "double" */ 

#define DBL_MAX 1 . 79769 3 1 3 486 2 3 1 47 0 e + 3 0 8 /*max decimal value of a "double"*/ 

#define DBL_MIN 4 . 9 40 6 5 64 5 84 1 2465 44e - 3 24 /*min decimal value of a "double"*/ 

#define FCHR_MAX 1048576 /* max size of a file in bytes */ 

#define FLT_DIG 7 /* digits of precision of a "float" */ 

#define FLT.MAX 3 . 40282346638528860e + 38 /*max decimal value of a "float" */ 

#define FLT_MIN 1 . 40 1 2984643248 1 707e-45 /*min decimal value of a "float" */ 

#define HUGE_ VAL 3 . 40282346638528860e + 38 /*error value returned by Math lib*/ 

#def ine INT_MAX 2147483647 /* max decimal value of an "int" */ 

#define INT_MIN -2147483648 /* min decimal value of an "int" */ 

#define LINK_MAX 32767 /* max # of links to a single file */ 

#define LONG_MAX 2147483647 /* max decimal value of a "long" */ 

#define LONG_MIN -2147483648 /* min decimal value of a "long" */ 

#define NAME_MAX 14 /* max # of characters in a file name */ 

#define OPEN_MAX 20 /* max # of files a process can have open */ 

#define PASS_MAX 8 /* max # of characters in a password */ 

#define PATH_MAX 256 /* max # of characters in a path name */ 

#define PID_MAX 30000 /* max value for a process ID */ 

#define PIPE_BUF 5120 /* max # bytes atomic in write to a pipe */ 

#define PIPE_MAX 5120 /* max # bytes written to a pipe in a write */ 

#define SHRT_MAX 32767 /* max decimal value of a "short" */ 

#define SHRT_MIN -32767 /* min decimal value of a "short" */ 

#def ine STD_BLK 1024 /* # bytes in a physical I/O block */ 

#define SYS_NMLN 9 /* # of chars in uname-returned strings */ 

#define UID_MAX 30000 /* max value for a user or group ID */ 

#def ine USI_MAX 4294967296 /* max decimal value of an "unsigned" */ 

#define WORD_BIT 32 /* # of bits in a "word" or "int" */ 
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NAME 

linenum — line number entries in a common object file 
SYNOPSIS 

#include <linenum.h> 

DESCRIPTION 

The cc command generates an entry in the object file for each C source line on 
which a breakpoint is possible [when invoked with the -g option; see cc(l)]. 
Users can then reference line numbers when using the appropriate software test 
system [see sdb( 1)]. The structure of these line number entries appears below. 

struct lineno 



union 



} ; 



long 
j long 

unsigned short 



l_symndx ; 
l_paddr ; 
l_addr ; 
llnno ; 



Numbering starts with one for each function. The initial line number entry for a 
function has IJnno equal to zero, and the symbol table index of the function's 
entry is in l_symndx. Otherwise, IJnno is non-zero, and Ijpaddr is the physical 
address of the code for the referenced line. Thus the overall structure is the fol- 
lowing: 



l_addr 


IJnno 


function symtab index 


0 


physical address 


line 


physical address 


line 


function symtab index 


0 


physical address 


line 


physical address 


line 



SEE ALSO 

cc(l), sdb(l), a.out(4). 
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NAME 

master — master configuration database 
DESCRIPTION 

The master configuration database is a collection of files. Each file contains 
configuration information for a device or module that may be included in the 
system. A file is named with the module name to which it applies. This collec- 
tion of files is maintained in a directory called /etc/master.d. Each individual 
file has an identical format. For convenience, this collection of files will be 
referred to as the master file, as though it was a single file. This will allow a 
reference to the master file to be understood to mean the individual file in the 
master.d directory that corresponds to the name of a device or module. The file 
is used by the mkboot(lM) program to obtain device information to generate the 
device driver and configurable module files. It is also used by the sysdef( 1M) 
program to obtain the names of supported devices, master consists of two parts; 
they are separated by a line with a dollar sign ($) in column 1 . Part 1 contains 
device information for both hardware and software devices, and loadable 
modules. Part 2 contains parameter declarations used in part 1. Any line with 
an asterisk (*) in column 1 is treated as a comment. 

Part 1, Description 

Hardware devices, software drivers and loadable modules are defined with a line 
containing the following information. Field 1 must begin in the left most posi- 
tion on the line. Fields are separated by white space (tab or blank). 

Field 1: element characteristics: 

o specify only once 

r required device 

b block device 

c character device 

a generate segment descriptor array 

t initialize cdevsw[].d_ttys 

s software driver 

f STREAMS driver 

m STREAMS module 

x not a driver; a loadable module 

number The first interrupt vector for an integral device 
Field 2: number of interrupt vectors required by a hardware device: 

" if none. 

Field 3: handler prefix (4 chars, maximum) 

Field 4: software driver external major number; " if not a 

software driver, or to be assigned during execution of 
drvinstall( 1M) 

Field 5: number of sub-devices per device; " if none 

Field 6: interrupt priority level of the device; " if none 

Field 7: dependency list (optional); this is a comma separated list of 

other drivers or modules that must be present in the 
configuration if this module is to be included 

For each module, two classes of information are required by mkboot( 1M): 
external routine references and variable definitions. Routine and 
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variable definition lines begin with white space and immediately follow 
the initial module specification line. These lines are free form, thus they 
may be continued arbitrarily between non-blank tokens as long as the 
first character of a line is white space. 

Part 1, Routine Reference Lines 

If the UNIX system kernel or other dependent module contains external refer- 
ences to a module, but the module is not configured, then these external refer- 
ences would be undefined. Therefore, the routine reference lines are used to pro- 
vide the information necessary to generate appropriate dummy functions at boot 
time when the driver is not loaded. 

Routine references are defined as follows: 

Field 1: routine name () 

Field 2: the routine type: one of 

{} routine_name(){} 

{nosys} 

routine_name() {return nosys();} 

{nodev} 

routine_name() {return nodev();} 

{false} routine_name() {return 0;} 

{true} routine_name() {return 1;} 

Part 1, Variable Definition Lines 

Variable definition lines are used to generate all variables required by the module. 
The variable generated may be of arbitrary size, be initialized or not, or be 
arrays containing an arbitrary number of elements. 
variable references are defined as follows: 

Field 1: variablename 

Field 2: [ expr ] — optional field used to indicate array size 

Field 3: (length) — required field indicating the size of the variable 

Field 4: ={ expr,... } — optional field used to initialize individual ele- 

ments of a variable 

The length field is mandatory. It is an arbitrary sequence of length specifiers, 
each of which may be one of the following: 

%i an integer 

%1 a long integer 

%s a short integer 

%c a single character 

%number a field which is number bytes long 

%number c a character string which is number bytes long 

For example, the length field 

( %8c %1 %0x58 %1 %c %c ) 

could be used to identify a variable consisting of a character string 8 -bytes long, 
a long integer, a 0x58 byte structure of any type, another long integer, and two 
characters. Appropriate alignment of each % specification is performed 
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(%number is word aligned) and the variable length is rounded up to the next 
word boundary during processing. 

The expressions for the optional array size and initialization are infix expressions 
consisting of the usual operators for addition, subtraction, multiplication, and 
division: +, — , *, and /. Multiplication and division have the higher precedence, 
but parentheses may be used to override the default order. The builtin functions 
min and max accept a pair of expressions, and return the appropriate value. The 
operands of the expression may be any mixture of the following: 



&name 



#name 



#C 



#C(name) 



#D 

#D(name) 

#M 

#M(name) 

name 

number 

string 



address of name where name is any symbol defined by the 
kernel, any module loaded or any variable definition line of 
any module loaded 

sizeof name where name is any variable name defined by a 
variable definition for any module loaded; the size is that 
of the individual variable— not the size of an entire array 
number of controllers present; this number is determined 
by the EDT for hardware devices, or by the number pro- 
vided in the system file for non-hardware drivers or 
modules 

number of controllers present for the module name ; this 
number is determined by the EDT for hardware devices, or 
by the number provided in the system file for non- 
hardware drivers or modules 

number of devices per controller taken directly from the 
current master file entry 

number of devices per controller taken directly from the 

master file entry for the module name 

the internal major number assigned to the current module 

if it is a device driver; zero of this module is not a device 

driver 

the internal major number assigned to the module name if 
it is a device driver: zero if that module is not a device 
driver 

value of a parameter as defined in the second part of 
master 

arbitrary number (octal, decimal, or hex allowed) 
a character string enclosed within double quotes (all of the 
character string conventions supported by the C language 
are allowed); this operand has a value which is the address 
of a character array containing the specified string 



When initializing a variable, one initialization expression should be provided for 
each %i, %1, %s, or %c of the length field. The only initializers allowed for a 
'%number c' are either a character string (the string may not be longer than 
number ), or an explicit zero. Initialization expressions must be separated by 
commas, and variable initialization will proceed element by element. Note that 
%number specification cannot be initialized— they are set to zero. Only the first 
element of an array can be initialized, the other elements are set to zero. If 
there are more initializers than size specifications, it is an error and execution of 
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the mkboot( 1M) program will be aborted. If there are fewer initializations than 
size specifications, zeros will be used to pad the variable. For example: 

={ "V2.L1", #C*#D, max(10,#D), #C(OTHER), #M(OTHER) } 

would be a possible initialization of the variable whose length field was given in 
the preceding example. 

Part 2, Description 

Parameter declarations may be used to define a value symbolically. Values can 
be associated with identifiers and these identifiers may be used in the variable 
definition lines. 

Parameters are defined as follows: 



Field 1 
Field 2 
Field 3 



EXAMPLE 



identifier (8 characters maximum) 

value, the value may be a number (decimal, octal, or hex 
allowed), or a string 



A sample master file for a tty device driver would be named "atty" if the device 
appeared in the EDT as "ATTY". The driver is a character device, the driver 
prefix is at, two interrupt vectors are used, and the interrupt priority is 6. In 
addition, another driver named "ATLOG" is necessary for the correct operation of 
the software associated with this device. 



♦FLAG #VEC PREFIX SOFT #DEV IPL DEPENDENCIES/VARIABLES 
tea 2 at - 2 6 ATLOG 



$ 



atpoint ( ) {false } 
at _ tty [ #C*#D ] ( %0x58 ) 

at_cnt ( %i ) ={ #C*#D } 
at.logma j ( %i ) ={ #M ( ATLOG ) 
at_ id ( %8c ) ={ ATID } 

at .table (%i%l%3 1%s ) 

={ max ( #C , ATMAX ) , 

&at_ tty , 

#C } 



ATID = "fred" 
ATMAX = 6 



} 



This master file will cause a routine named atpoint to be generated by the boot 
program if the ATTY driver is not loaded, and there is a reference to this routine 
from any other module loaded. When the driver is loaded, the variables atjty, 
at_cnt, atjogmaj, atjd , and atjable will be allocated and initialized as specified. 
Due to the t flag, the djtys field in the character device switch table will be ini- 
tialized to point to attty (the first variable definition line contains the variable 
whose address will be stored in djtys). The ATTY driver would reference these 
variables by coding: 
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extern struct tty at _tty[]; 
extern int at_cnt; 
extern int atjogmaj; 
extern char at id[8]; 
extern struct f~ 

int member In- 
struct tty *member2; 
char junk[31]; 
short member3; 

) at Jable; 



FILES 

/etc/master.d/* 

SEE ALSO 

system(4). 

drvinstall(lM), mkboot(lM), sysdef(lM) in the System Administrator's Reference 
Manual. 
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NAME 

mnttab — mounted file system table 
SYNOPSIS 

#include <mnttab.h> 

DESCRIPTION 

mnttab resides in directory /etc and contains a table of devices, mounted by the 
mount( 1M) command, in the following structure as defined by <mnttab.h>: 

struct mnttab { 

char mt_dev[32]; 

char mt_filsys[32]; 

short mt_ro_flg; 

time t mt time; 

}; 

Each entry is 70 bytes in length; the first 32 bytes are the null-padded name of 
the place where the special file is mounted; the next 32 bytes represent the null- 
padded root name of the mounted special file; the remaining 6 bytes contain the 
mounted special file's read/ write permissions and the date on which it was 
mounted. 

The maximum number of entries in mnttab is based on the system parameter 
NMOUNT located in /etc/master.d/kernel, which defines the number of allow- 
able mounted special files. 

SEE ALSO 

mount(lM), setmnt(lM) in the System Administrator's Reference Manual. 
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NAME 

passwd — password file 
DESCRIPTION 

passwd contains for each user the following information: 

login name 
encrypted password 
numerical user ID 
numerical group ID 

GCOS job number, box number, optional GCOS user ID 
initial working directory 
program to use as shell 

This is an ASCII file. Each field within each user's entry is separated from the 
next by a colon. The GCOS field is used only when communicating with that 
system, and in other installations can contain any desired information. Each 
user is separated from the next by a new-line. If the password field is null, no 
password is demanded; if the shell field is null, the shell itself is used. 

This file resides in directory /etc. Because of the encrypted passwords, it can 
and does have general read permission and can be used, for example, to map 
numerical user IDs to names. 

The encrypted password consists of 13 characters chosen from a 64-character 
alphabet (., /, 0—9, A— Z, a— z), except when the password is null, in which case 
the encrypted password is also null. Password aging is effected for a particular 
user if his encrypted password in the password file is followed by a comma and 
a non-null string of characters from the above alphabet. (Such a string must be 
introduced in the first instance by the super-user.) 

The first character of the age, M say, denotes the maximum number of weeks for 
which a password is valid. A user who attempts to login after his password has 
expired will be forced to supply a new one. The next character, m say, denotes 
the minimum period in weeks which must expire before the password may be 
changed. The remaining characters define the week (counted from the begin- 
ning of 1970) when the password was last changed. (A null string is equivalent 
to zero.) M and m have numerical values in the range 0—63 that correspond to 
the 64-character alphabet shown above (i.e., / = 1 week; z = 63 weeks). If m = 
M — 0 (derived from the string . or ..) the user will be forced to change his pass- 
word the next time he logs in (and the "age" will disappear from his entry in 
the password file). If m > M (signified, e.g., by the string ./) only the super- 
user will be able to change the password. 

FILES 

/etc/passwd 
SEE ALSO 

a641(3C), getpwent(3C), group(4). 

login(l), passwd(l) in the User's Reference Manual. 
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NAME 

plot — graphics interface 
DESCRIPTION 

Files of this format are produced by routines described in plot( 3X) and are inter- 
preted for various devices by commands described in tplot( 1G). A graphics file 
is a stream of plotting instructions. Each instruction consists of an ASCII letter 
usually followed by bytes of binary information. The instructions are executed 
in order. A point is designated by four bytes representing the x and y values; 
each value is a signed integer. The last designated point in an 1, m, n, or p 
instruction becomes the "current point" for the next instruction. 

Each of the following descriptions begins with the name of the corresponding 
routine in plot( 3X). 

m move: The next four bytes give a new current point. 

n cont: Draw a line from the current point to the point given by the next four 
bytes [see tplot( 1G)]. 

p point: Plot the point given by the next four bytes. 

1 line: Draw a line from the point given by the next four bytes to the point 
given by the following four bytes. 

t label: Place the following ASCII string so that its first character falls on the 
current point. The string is terminated by a new-line. 

e erase: Start another frame of output. 

f linemod: Take the following string, up to a new-line, as the style for 
drawing further lines. The styles are "dotted", "solid", "longdashed", 
"shortdashed", and "dotdashed". Effective only for the — T4014 and —Tver 
options of tplot(lG) (TEKTRONIX 4014 terminal and Versatec plotter). 

s space: The next four bytes give the lower left corner of the plotting area; the 
following four give the upper right corner. The plot will be magnified or 
reduced to fit the device as closely as possible. 

Space settings that exactly fill the plotting area with unity scaling appear below 
for devices supported by the filters of tplot(lG). The upper limit is just outside 
the plotting area. In every case the plotting area is taken to be square; points 
outside may be displayable on devices whose face is not square. 

DASI 300 space(0, 0, 4096, 4096); 

DASI 300s space(0, 0, 4096, 4096); 

DASI 450 space(0, 0, 4096, 4096); 

TEKTRONIX 4014 space(0, 0, 3120, 3120); 

Versatec plotter space(0, 0, 2048, 2048); 

SEE ALSO 

plot(3X), gps(4), term(5). 

graph(lG), tplot(lG) in the User's Reference Manual. 

WARNING 

The plotting library plot( 3X) and the curses library curses( 3X) both use the 
names erase() and move(). The curses versions are macros. If you need both 
libraries, put the plot( 3X) code in a different source file than the curses( 3X) code. 
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and/or #undef move() and erase() in the plot( 3X) code. 
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NAME 

pnch — file format for card images 
DESCRIPTION 

The PNCH format is a convenient representation for files consisting of card 
images in an arbitrary code. 

A PNCH file is a simple concatenation of card records. A card record consists of 
a single control byte followed by a variable number of data bytes. The control 
byte specifies the number (which must lie in the range 0-80) of data bytes that 
follow. The data bytes are 8 -bit codes that constitute the card image. If there 
are fewer than 80 data bytes, it is understood that the remainder of the card 
image consists of trailing blanks. 
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NAME 

profile — setting up an environment at login time 

SYNOPSIS 

/etc/profile 
$HOME /.profile 

DESCRIPTION 

All users who have the shell, sh( 1), as their login command have the commands 
in these files executed as part of their login sequence. 

/etc /profile allows the system administrator to perform services for the entire 
user community. Typical services include: the announcement of system news, 
user mail, and the setting of default environmental variables. It is not unusual 
for /etc /profile to execute special actions for the root login or the su( 1) com- 
mand. Computers running outside the Eastern time zone should have the line 

. /etc/TIMEZONE 

included early in /etc /profile (see timezone(4)). 

The file $HOME/ .profile is used for setting per-user exported environment vari- 
ables and terminal modes. The following example is typical (except for the com- 
ments): 

# Make some environment variables global 
export MAIL PATH TERM 

# Set file creation mask 
umask 027 

# Tell me when new mail comes in 
M AIL- /usr /mail /$LOGN AME 

# Add my /bin directory to the shell search sequence 
P ATH=$PATH:$HOME /bin 

# Set terminal type 
while : 

do echo "terminal: \c" 

read TERM 

if [ -f $ {TERMINFO:-/ usr /lib / terminfo} /? /$TERM ] 
then break 

elif [ — f /usr/lib/terminfo/?/$TERM ] 
then break 

else echo "invalid term $TERM" 1 > &2 
fi 

done 

# Initialize the terminal and set tabs 

# The environmental variable TERM must have been exported 

# before the "tput init" command is executed, 
tput init 

# Set the erase character to backspace 
stty erase '*H' echoe 
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FILES 

/etc /TIMEZONEtimezone environment 
$ HOME /.profile user-specific environment 
/etc/profile system- wide environment 

SEE ALSO 

terminfo(4), timezone(4), environ(5), term(5). 

env(l), login(l), mail(l), sh(l), stty(l), su(l), tput(l) in the Users Reference 
Manual 

su(lM) in the System Administrator s Reference Manual. 

User's Guide. 

Chapter 10 in the Programmer's Guide. 

NOTES 

Care must be taken in providing system- wide services in /etc/profile. Personal 
.profile files are better for serving all but the most global needs. 
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NAME 

reloc — relocation information for a common object file 
SYNOPSIS 

#include <reloc.h> 

DESCRIPTION 

Object files have one relocation entry for each relocatable reference in the text or 
data. If relocation information is present, it will be in the following format. 



struct 

[ 


reloc 




1 


long 


r_vaddr ; /* (virtual) address of reference */ 




long 


r_symndx ; /* index into symbol table */ 


); 


ushort 


r_type ; /* relocation type */ 


# define 


RABS 


0 


#define 


R DIR32 


06 


#define 


R DIR32S 


012 



As the link editor reads each input section and performs relocation, the reloca- 
tion entries are read. They direct how references found within the input section 
are treated. 

RABS The reference is absolute and no relocation is necessary. 

The entry will be ignored. 

R DIR32 A direct 32-bit reference to the symbol's virtual address. 

R DIR32S A direct 32-bit reference to the symbol's virtual address, 

with the 3 2 -bit value stored in the reverse order in the 
object file. 

More relocation types exist for other processors. Equivalent relocation types on 
different processors have equal values and meanings. New relocation types will 
be defined (with new values) as they are needed. 

Relocation entries are generated automatically by the assembler and automati- 
cally used by the link editor. Link editor options exist for both preserving and 
removing the relocation entries from object files. 

SEE ALSO 

as(l), ld(l), a.out(4), syms(4). 
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NAME 

rfmaster — Remote File Sharing name server master file 
DESCRIPTION 

The rfmaster file is an ASCII file that identifies the hosts that are responsible for 
providing primary and secondary domain name service for Remote File Sharing 
domains. This file contains a series of records, each terminated by a newline; a 
record may be extended over more than one line by escaping the newline char- 
acter with a backslash ("\"). The fields in each record are separated by one or 
more tabs or spaces. Each record has three fields: 

name type data 

The type field, which defines the meaning of the name and data fields, has three 
possible values: 

p The p type defines the primary domain name server. For this type, name 
is the domain name and data is the full host name of the machine that is 
the primary name server. The full host name is specified as 
domain.nodename. There can be only one primary name server per 
domain. 

s The s type defines a secondary name server for a domain. Name and data 
are the same as for the p type. The order of the s entries in the rfmaster 
file determines the order in which secondary name servers take over 
when the current domain name server fails. 

a The a type defines a network address for a machine. Name is the full 
domain name for the machine and data is the network address of the 
machine. The network address can be in plain ASCII text or it can be pre- 
ceded by a \x to be interpreted as hexadecimal notation. (See the docu- 
mentation for the particular network you are using to determine the net- 
work addresses you need.) 

There are at least two lines in the rfmaster file per domain name server: one p 
and one a line, to define the primary and its network address. There should 
also be at least one secondary name server in each domain. 

This file is created and maintained on the primary domain name server. When a 
machine other than the primary tries to start Remote File Sharing, this file is 
read to determine the address of the primary. If rfmaster is missing, the -p 
option of rfstart must be used to identify the primary. After that, a copy of the 
primary's rfmaster file is automatically placed on the machine. 

Domains not served by the primary can also be listed in the rfmaster file. By 
adding primary, secondary, and address information for other domains on a net- 
work, machines served by the primary will be able to share resources with 
machines in other domains. 

A primary name server may be a primary for more than one domain. However, 
the secondaries must then also be the same for each domain served by the pri- 
mary. 
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Example 

An example of an rfmaster file is shown below. (The network address exam- 
ples, compl.serve and comp2.serve, are STARLAN network addresses.) 



ccs p 

ccs s 

ccs.comp2 a 

ccs.compl a 



ccs.compl 
ccs.comp2 
comp2. serve 
compl.serve 



NOTE: If a line in the rfmaster file begins with a # character, the entire line 
will be treated as a comment. 



FILES 

/usr /nserve /rfmaster 
SEE ALSO 

rfstart(lM) in the System Administrator's Reference Manual. 
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NAME 

sccsfile - format of SCCS file 
DESCRIPTION 

An SCCS (Source Code Control System) file is an ASCII file. It consists of six 
logical parts: the checksum, the delta table (contains information about each 
delta), user names (contains login names and/or numerical group IDs of users 
who may add deltas), flags (contains definitions of internal keywords), comments 
(contains arbitrary descriptive information about the file), and the body (contains 
the actual text lines intermixed with control lines). 

Throughout an SCCS file there are lines which begin with the ASCII SOH (start 
of heading) character (octal 001). This character is hereafter referred to as the 
control character and will be represented graphically as @. Any line described 
below which is not depicted as beginning with the control character is prevented 
from beginning with the control character. 

Entries of the form DDDDD represent a five-digit string (a number between 
00000 and 99999). 

Each logical part of an SCCS file is described in detail below. 

Checksum 

The checksum is the first line of an SCCS file. The form of the line is: 
@hDDDDD 

The value of the checksum is the sum of all characters, except those of 
the first line. The @h provides a magic number of (octal) 064001. 

Delta table 

The delta table consists of a variable number of entries of the form: 

@S DDDDD /DDDDD /DDDDD 

@d <type> <SCCS ID> yr/mo/da hr:mi:se <pgmr> DDDDD DDDDD 
@i DDDDD ... 

@X DDDDD ... 

@g DDDDD ... 

@m <MR number > 



@c < comments > ... 



@e 

The first line (@s) contains the number of lines 
inserted/deleted/unchanged, respectively. The second line (@d) con- 
tains the type of the delta (currently, normal: D, and removed: R), the 
SCCS ID of the delta, the date and time of creation of the delta, the 
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login name corresponding to the real user ID at the time the delta was 
created, and the serial numbers of the delta and its predecessor, respec- 
tively. 

The @i, @x, and @g lines contain the serial numbers of deltas included, 
excluded, and ignored, respectively. These lines are optional. 

The @m lines (optional) each contain one MR number associated with 
the delta; the @c lines contain comments associated with the delta. 

The @e line ends the delta table entry. 

User names 

The list of login names and/or numerical group IDs of users who may 
add deltas to the file, separated by new-lines. The lines containing these 
login names and/or numerical group IDs are surrounded by the brack- 
eting lines @u and @U. An empty list allows anyone to make a delta. 
Any line starting with a ! prohibits the succeeding group or user from 
making deltas. 

Flags 

Keywords used internally. [See admin( 1) for more information on their 
use.] Each flag line takes the form: 

@f <flag> < optional text> 

The following flags are defined: 



@f t 


<type of program > 


@f V 


< program name> 


@f i 


< keyword string > 


@f b 




@f m 


< module name> 


@ff 


< floor > 


@f c 


< ceiling > 


@f d 


<default-sid> 


@f n 




@f j 




@f i 


< lock-releases > 


@f q 


<user defined > 


@f z 


< reserved for use in interfaces > 



The t flag defines the replacement for the %Y% identification keyword. 
The v flag controls prompting for MR numbers in addition to comments; 
if the optional text is present it defines an MR number validity checking 
program. The i flag controls the warning/error aspect of the "No id 
keywords" message. When the i flag is not present, this message is only 
a warning; when the i flag is present, this message will cause a "fatal" 
error (the file will not be gotten, or the delta will not be made). When 
the b flag is present the — b keyletter may be used on the get command 
to cause a branch in the delta tree. The m flag defines the first choice 
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for the replacement text of the %M% identification keyword. The f flag 
defines the "floor" release; the release below which no deltas may be 
added. The c flag defines the "ceiling" release; the release above which 
no deltas may be added. The d flag defines the default SID to be used 
when none is specified on a get command. The n flag causes delta to 
insert a "null" delta (a delta that applies no changes) in those releases 
that are skipped when a delta is made in a new release (e.g., when delta 
5.1 is made after delta 2.7, releases 3 and 4 are skipped). The absence 
of the n flag causes skipped releases to be completely empty. The j flag 
causes get to allow concurrent edits of the same base SID. The 1 flag 
defines a list of releases that are locked against editing [get( 1) with the 
— e keyletter]. The q flag defines the replacement for the %Q% 
identification keyword. The z flag is used in certain specialized interface 
programs. Comments Arbitrary text is surrounded by the bracketing lines 
@t and @T. The comments section typically will contain a description 
of the file's purpose. 

Body 

The body consists of text lines and control lines. Text lines do not begin 
with the control character, control lines do. There are three kinds of 
control lines: insert, delete, and end, represented by: 

@1 DDDDD 
@D DDDDD 
@E DDDDD 

respectively. The digit string is the serial number corresponding to the 
delta for the control line. 

SEE ALSO 

admin(l), delta(l), get(l), prs(l). 
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NAME 

scnhdr — section header for a common object file 
SYNOPSIS 

#include < scnhdr. h> 

DESCRIPTION 

Every common object file has a table of section headers to specify the layout of 
the data within the file. Each section within an object file has its own header. 
The C structure appears below. 

struct scnhdr 



char 
long 
long 
long 
long 
long 
long 

unsigned short s_nreloc; /* # reloc entries */ 

unsigned short s_nlnno; /* # line number entries */ 

long s_flags; /* flags */ 

) / 

File pointers are byte offsets into the file; they can be used as the offset in a call 
to FSEEK [see ldfcn( 4)]. If a section is initialized, the file contains the actual 
bytes. An uninitialized section is somewhat different. It has a size, symbols 
defined in it, and symbols that refer to it. But it can have no relocation entries, 
line numbers, or data. Consequently, an uninitialized section has no raw data in 
the object file, and the values for sjcwptr, sjelptr, sjnnoptr, sjireloc, and 
sjilnno are zero. 

Cf?F AT SO 

ld(l), fseek(3S), a.out(4). 



s_name[SYMNMLEN]; /* section name */ 
s_paddr; /* physical address */ 

s_vaddr; /* virtual address */ 

s_size; /* section size */ 

s_scnptr; /* file ptr to raw data */ 
s_relptr; /* file ptr to relocation */ 

sjnnoptr; /* file ptr to line numbers */ 
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NAME 

scr_dump — format of curses screen image file. 

SYNOPSIS 

scrdump(file) 

DESCRIPTION 

The curses( 3X) function scr_dump() will copy the contents of the screen into a 
file. The format of the screen image is as described below. 

The name of the tty is 20 characters long and the modification time (the mtime 
of the tty that this is an image of) is of the type timej. All other numbers and 
characters are stored as chtype (see <curses.h>). No newlines are stored 
between fields. 



< magic number: octal 0433 > 
<name of tty> 

<mod time of tty > 

< columns > < lines > 

<line length > < chars in line> 
<line length > < chars in line> 



< labels? > 

< cursor row> < cursor column > 



for each line on the screen 



1, if soft screen labels are present 



Only as many characters as are in a line will be listed. For example, if the <line 
length> is 0, there will be no characters following Kline length>. If <labels?> 
is TRUE, following it will be 

< number of labels > 

< label width > 

< chars in label 1 > 

< chars in label 2> 



SEE ALSO 

curses(3X). 
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NAME 

syms — common object file symbol table format 
SYNOPSIS 

#include <syms.h> 

DESCRIPTION 

Common object files contain information to support symbolic software testing 
[see sdb( 1)]. Line number entries, linenum( 4), and extensive symbolic informa- 
tion permit testing at the C source level. Every object file's symbol table is 
organized as shown below. 

File name 1. 

Function 1. 

Local symbols for function 1. 

Function 2. 

Local symbols for function 2. 

Static externs for file 1. 

File name 2. 

Function 1. 

Local symbols for function 1. 

Function 2. 

Local symbols for function 2. 

Static externs for file 2. 



Defined global symbols. 

Undefined global symbols. 

The entry for a symbol is a fixed-length structure. The members of the structure 
hold the name (null padded), its value, and other information. The C structure 
is given below. 

#define SYMNMLEN 8 

#define FILNMLEN 14 

#define DIMNUM 4 



struct syment 



union 

{ 



/* all ways to get symbol name */ 



char 
struct 
{ 

long 
long 
) _n_n; 

char * n nptr[21; 

} _n; 



/* == OL when in string table */ 
/* location of name in table */ 

/* allows overlaying */ 



n_name[SYMNMLEN]; /* symbol name */ 

nzeroes; 
n_offset; 
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long 


n_value; 


/* value of symbol */ 


short 


n scnum; 


/* section number */ 


unsigned short 


ntype; 


/* type and derived type */ 


char 


n_sclass; 


/* storage class */ 


char 

}; 


n_numaux; 


/* number of aux entries */ 


# define n_name 


n. n name 




# define n zeroes 


n. n n. n zeroes 


#define n offset 


n. n n. n offset 


# define n_nptr 


_n._n_nptr[l] 




Meaningful values and explanations for 


them are given in both syms.h and 


Common Object File Format . 


Anyone who needs to interpret the entries should 



seek more information in these sources. Some symbols require more informa- 
tion than a single entry; they are followed by auxiliary entries that are the same 
size as a symbol entry. The format follows. 

union auxent 

{ 

struct 



long xjagndx; 

union 

{ 

struct 

{ 

unsigned short 
unsigned short 

} x_lnsz; 
long x_fsize; 

} x_misc; 
union 
{ 

struct 



xlnno; 

xsize; 



} 

struct 

{ 



} 

} 

unsigned short 
} x_sym; 
struct 



long xjnnoptr; 
long x_endndx; 
x_fcn; 



unsigned short x_dimen[DIMNUM]; 

x_ary; 

x_fcnary; 

x_tvndx; 



char x_fname[FILNMLEN]; 
} x_file; 
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struct 



long xscnlen; 
unsigned short x nreloc; 
unsigned short x_nlinno; 
} x_scn; 



struct 



long x_tvfill; 

unsigned short x tvlen; 
unsigned short x_tvran[2]; 

} x tv; 

}; 

Indexes of symbol table entries begin at zero. 

SEE ALSO 

sdb(l), a.out(4), linenum(4). 

"Common Object File Format" in the Programming Guide. 

WARNINGS 

On machines on which ints are equivalent to longs, all longs have their type 
changed to int. Thus the information about which symbols are declared as 
longs and which, as ints, does not show up in the symbol table. 
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NAME 

system — system configuration information table 
DESCRIPTION 

This file is used by the boot program to obtain configuration information that 
cannot be obtained from the equipped device table (EDT) at system boot time. 
This file generally contains a list of software drivers to include in the load, the 
assignment of system devices such as pipedev and swapdev, as well as instruc- 
tions for manually overriding the drivers selected by the self-configuring boot 
process. 

The syntax of the system file is given below. The parser for the /etc/system 
file is case sensitive. All upper case strings in the syntax below should be upper 
case in the /etc/system file as well. Nonterminal symbols are enclosed in angle 
brackets "<>" while optional arguments are enclosed in square brackets "[]". 
Ellipses "..." indicate optional repetition of the argument for that line. 

<fname> ::= pathname 

< string > driver file name from /boot or EDT entry name 

< device > ::= special device name | DEV(<major>,<minor>) 

<major> < number > 

< minor > < number > 

< number > ::= decimal, octal or hex literal 

The lines listed below may appear in any order. Blank lines may be inserted at 
any point. Comment lines must begin with an asterisk. Entries for EXCLUDE 
and INCLUDE are cumulative. For all other entries, the last line to appear in 
the file is used — any earlier entries are ignored. 

BOOT: <fname> 

specifies the kernel a. out file to be booted; if the file is 
fully resolved [such as that produced by the mkunix( 1M) 
program] then all other lines in the system file have no 
effect. 

EXCLUDE: [ <string> ] ... 

specifies drivers to exclude from the load even if the 
device is found in the EDT. 

INCLUDE: [ < string >[(< number >)] ] ... 

specifies software drivers or loadable modules to be 
included in the load. This is necessary to include the 
drivers for software "devices". The optional < number > 
(parenthesis required) specifies the number of "devices" to 
be controlled by the driver (defaults to 1). This number 
corresponds to the builtin variable #c which may be 
referred to by expressions in part one of the /etc/master 
file. 

ROOTDEV: < device > 

identifies the device containing the root file system. 
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FILES 



SWAPDEV: < device > < number > < number > 

identifies the device to be used as swap space, the block 
number the swap space starts at, and the number of swap 
blocks available. 

PIPEDEV: < device > 

identifies the device to be used for pipe space. 



/etc/system 



SEE ALSO 

master(4). 

crash(lM), mkunix(lM), mkboot(lM) in the System Administrator's Reference 
Manual. 
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NAME 

term — format of compiled term file. 

SYNOPSIS 

/usr /lib /terminfo /?/* 

DESCRIPTION 

Compiled terminfo( 4) descriptions are placed under the directory 
/usr /lib /terminfo. In order to avoid a linear search of a huge UNIX system direc- 
tory, a two-level scheme is used: /usr /lib/ terminfo /c /name where name is the 
name of the terminal, and c is the first character of name. Thus, att4425 can be 
found in the file /usr/lib /terminfo /a/ att4425. Synonyms for the same terminal 
are implemented by multiple links to the same compiled file. 

The format has been chosen so that it will be the same on all hardware. An 8- 
bit byte is assumed, but no assumptions about byte ordering or sign extension 
are made. Thus, these binary terminfo( 4) files can be transported to other 
hardware with 8 -bit bytes. 

Short integers are stored in two 8-bit bytes. The first byte contains the least 
significant 8 bits of the value, and the second byte contains the most significant 
8 bits. (Thus, the value represented is 256*second+first.) The value —1 is 
represented by 0377,0377, and the value —2 is represented by 0376,0377; other 
negative values are illegal. Computers where this does not correspond to the 
hardware read the integers as two bytes and compute the result, making the 
compiled entries portable between machine types. The —1 generally means that 
a capability is missing from this terminal. The —2 means that the capability has 
been cancelled in the terminfo ( 4) source and also is to be considered missing. 

The compiled file is created from the source file descriptions of the terminals 
(see the —I option of infocmp (1M)) by using the terminfo (4) compiler, tic( 1M), 
and read by the routine setupterm(). (See curses( 3X).) The file is divided into 
six parts: the header, terminal names, boolean flags, numbers, strings, and string 
table. 

The header section begins the file. This section contains six short integers in the 
format described below. These integers are (1) the magic number (octal 0432); 
(2) the size, in bytes, of the names section; (3) the number of bytes in the 
boolean section; (4) the number of short integers in the numbers section; (5) the 
number of offsets (short integers) in the strings section; (6) the size, in bytes, of 
the string table. 

The terminal names section comes next. It contains the first line of the ter- 
minfo (4) description, listing the various names for the terminal, separated by the 
bar ( | ) character (see term(5)). The section is terminated with an ASCII NUL 
character. 

The boolean flags have one byte for each flag. This byte is either 0 or 1 as the 
flag is present or absent. The value of 2 means that the flag has been cancelled. 
The capabilities are in the same order as the file <term.h>. 

Between the boolean section and the number section, a null byte will be 
inserted, if necessary, to ensure that the number section begins on an even byte. 
All short integers are aligned on a short word boundary. 
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The numbers section is similar to the boolean flags section. Each capability 
takes up two bytes, and is stored as a short integer. If the value represented is 
— 1 or —2, the capability is taken to be missing. 

The strings section is also similar. Each capability is stored as a short integer, in 
the format above. A value of —1 or —2 means the capability is missing. Other- 
wise, the value is taken as an offset from the beginning of the string table. Spe- 
cial characters in "X or \c notation are stored in their interpreted form, not the 
printing representation. Padding information ($<nn>) and parameter informa- 
tion (%x) are stored intact in uninterpreted form. 

The final section is the string table. It contains all the values of string capabili- 
ties referenced in the string section. Each string is null terminated. 

Note that it is possible for setupterm() to expect a different set of capabilities 
than are actually present in the file. Either the database may have been updated 
since setupterm() has been recompiled (resulting in extra unrecognized entries 
in the file) or the program may have been recompiled more recently than the 
database was updated (resulting in missing entries). The routine setupterm() 
must be prepared for both possibilities — this is why the numbers and sizes are 
included. Also, new capabilities must always be added at the end of the lists of 
boolean, number, and string capabilities. 

As an example, an octal dump of the description for the AT&T Model 37 KSR is 
included: 

37!tty37lATStT model 37 teletype, 
he, os, xon, 

bel =/v G, cr=\r, cub1=\b, crud1=\n, cuu1=\E7, hd=\E9, 
hu=\E8, ind=\n, 
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032 


001 
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\0 
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\0 
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377 
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377 
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0000160 
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it 


\0 
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\0 
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377 
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0 


\0 
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\0 
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\0 


\n 


\0 
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\0 


\b 


\0 


033 
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\0 
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9 


\0 
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7 
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\0 


\0 
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Some limitations: total compiled entries cannot exceed 4096 bytes; all entries in 
the name field cannot exceed 128 bytes. 

FILES 

/usr/lib/terminfo/?/* compiled terminal description database 

/usr/include/term.h terminfo( 4) header file 

SEE ALSO 

curses(3X), terminfo(4), term(5). 

infocmp(lM) in the System Administrator's Reference Manual. 

Chapter 10 of the Programmer's Guide. 
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NAME 

terminfo — terminal capability data base 
SYNOPSIS 

/usr /lib /terminfo /?/ * 

DESCRIPTION 

terminfo is a compiled database (see tic( 1M)) describing the capabilities of termi- 
nals. Terminals are described in terminfo source descriptions by giving a set of 
capabilities which they have, by describing how operations are performed, by 
describing padding requirements, and by specifying initialization sequences. 
This database is used by applications programs, such as vi( 1) and curses( 3X), so 
they can work with a variety of terminals without changes to the programs. To 
obtain the source description for a terminal, use the —I option of infocmp( 1M). 

Entries in terminfo source files consist of a number of comma-separated fields. 
White space after each comma is ignored. The first line of each terminal 
description in the terminfo database gives the name by which terminfo knows the 
terminal, separated by bar ( | ) characters. The first name given is the most 
common abbreviation for the terminal (this is the one to use to set the environ- 
ment variable TERM in $HOME/. pro file; see profile (4)), the last name given 
should be a long name fully identifying the terminal, and all others are under- 
stood as synonyms for the terminal name. All names but the last should contain 
no blanks and must be unique in the first 14 characters; the last name may con- 
tain blanks for readability. 

Terminal names (except for the last, verbose entry) should be chosen using the 
following conventions. The particular piece of hardware making up the terminal 
should have a root name chosen, for example, for the AT&T 4425 terminal, 
att4425. Modes that the hardware can be in, or user preferences, should be indi- 
cated by appending a hyphen and an indicator of the mode. See term(5) for 
examples and more information on choosing names and synonyms. 

CAPABILITIES 

In the table below, the Variable is the name by which the C programmer (at the 
terminfo level) accesses the capability. The Capname is the short name for this 
variable used in the text of the database. It is used by a person updating the 
database and by the tput( 1) command when asking what the value of the capa- 
bility is for a particular terminal. The Termcap Code is a two-letter code that 
corresponds to the old termcap capability name. 

Capability names have no hard length limit, but an informal limit of 5 characters 
has been adopted to keep them short. Whenever possible, names are chosen to 
be the same as or similar to the ANSI X3. 64-1979 standard. Semantics are also 
intended to match those of the specification. 

All string capabilities listed below may have padding specified, with the excep- 
tion of those used for input. Input capabilities, listed under the Strings section 
in the table below, have names beginning with key_. The following indicators 
may appear at the end of the Description for a variable. 
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(G) indicates that the string is passed through tparm() with parameters 
(parms) as given (#p. 

(*) indicates that padding may be based on the number of lines affected. 

tVi 

(#j.) indicates the i parameter. 



Variable 


Cap- 

name 


Termcap 

Code 


Description 


Booleans: 


auto_left_margin 


bw 


bw 


cubl wraps from column 0 to last column 


autorightmargin 


am 


am 


Terminal has automatic margins 


noescctlc 


xsb 


xb 


Beehive (fl=escape, f2=ctrl C) 


ceol_standout_glitch 


xhp 


xs 


Standout not erased by overwriting (hp) 


eatnewline^glitch 


xenl 


xn 


Newline ignored after 80 cols (Concept) 


eraseoverstrike 


eo 


eo 


Can erase overstrikes with a blank 


generictype 


g n 


g n 


Generic line type (e.g. dialup, switch). 


hard_copy 


he 


he 


Hardcopy terminal 


hardcursor 


chts 


HC 


Cursor is hard to see. 


has_meta_key 


km 


km 


Has a meta key (shift, sets parity bit) 


has_status_line 


hs 


hs 


Has extra "status line" 


insert_null_glitch 


in 


in 


Insert mode distinguishes nulls 


memoryabove 


da 


da 


Display may be retained above the screen 


memory below 


db 


db 


Display may be retained below the screen 


moveinsertmode 


mir 


mi 


Safe to move while in insert mode 


movestandoutmode 


msgr 


ms 


Safe to move in standout modes 


needsxonxoff 


nxon 


nx 


Padding won't work, xon/xoff required 


nonrevrmcup 


nrrmc 


NR 


smeup does not reverse rmeup 


no_pad_char 


npc 


NP 


Pad character doesn't exist 


overstrike 


os 


os 


Terminal overstrikes on hard-copy terminal 


prtrsilent 


mc5i 


5i 


Printer won't echo on screen. 


statuslineescok 


eslok 


es 


Escape can be used on the status line 


desttabsmagicsmso 


xt 


xt 


Destructive tabs, magic smso char (tl061) 


tilde_glitch 


hz 


hz 


Hazeltine; can't print tildesQ 


transparentunderline 


ul 


ul 


Underline character overstrikes 


xonxoff 


xon 


xo 


Terminal uses xon/xoff handshaking 


Numbers: 


columns 


cols 


CO 


Number of columns in a line 


inittabs 


it 


it 


Tabs initially every # spaces. 


labelheight 


lh 


lh 


Number of rows in each label 


labelwidth 


lw 


lw 


Number of cols in each label 


lines 


lines 


li 


Number of lines on screen or page 


lines_of_memory 


lm 


lm 


Lines of memory if > lines; 0 means varies 


magic_cookie_glitch 


xmc 


sg 


Number blank chars left by smso or rmso 


numlabels 


nlab 


N1 


Number of labels on screen (start at 1) 


paddingbaudrate 


pb 


P b 


Lowest baud rate where padding needed 


virtualterminal 


vt 


vt 


Virtual terminal number (UNIX system) 


width status line 


wsl 


ws 


Number of columns in status line 
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Strings: 



acschars 


acsc 


ac 


back tab 


cbt 


bt 


bell 


bel 


bl 


carriagereturn 


cr 


cr 


changescrollregion 


csr 


cs 


char^padding 


rmp 


rP 


clearalltabs 


tbc 


ct 


clearmargins 


mgc 


MC 


clearscreen 


clear 


cl 


clrbol 


ell 


cb 


clreol 


el 


ce 


clreos 


ed 


cd 


columnaddress 


hpa 


ch 


commandcharacter 


cmdch 


CC 


cursoraddress 


cup 


cm 


cursordown 


cudl 


do 


cursorhome 


home 


ho 


cursorin visible 


civis 


vi 


cursorleft 


cubl 


le 


cursormemaddress 


mrcup 


CM 


cursornormal 


cnorm 


ve 


cursorright 


cufl 


nd 


cursor Jtojl 


11 


11 


cursorup 


cuui 


up 


cursorvisible 


cvvis 


vs 


deletecharacter 


dchl 


dc 


deleteline 


dll 


dl 


dis_status_line 


dsl 


ds 


downhalfline 


hd 


hd 


enaacs 


enacs 


eA 


enteraltcharsetmode 


smacs 


as 


enterammode 


smam 


SA 


enterblinkmode 


blink 


mb 


enterboldmode 


bold 


md 


entercamode 


smcup 


ti 


enterdeletemode 


smdc 


dm 


enterdimmode 


dim 


mh 


enter insert mode 


smir 


im 


enter j^rotectedmode 


prot 


mp 


enter_reverse_mode 


rev 


mr 


entersecuremode 


in vis 


mk 


enterjstandoutjmode 


smso 


so 


enterunderlinemode 


smul 


us 


enterxonmode 


smxon 


SX 


erase_chars 


ech 


ec 


exit_alt_charset_mode 


rmacs 


ae 


exitammode 


rmam 


RA 


exitattributemode 


sgrO 


me 



Graphic charset pairs aAbBcC - def=vtl00+ 
Back tab 

Audible signal (bell) 

Carriage return (*) 

Change to lines #1 thru #2 (vtlOO) (G) 

Like ip but when in replace mode 
Clear all tab stops 
Clear left and right soft margins 
Clear screen and home cursor (*) 

Clear to beginning of line, inclusive 
Clear to end of line 
Clear to end of display (*) 

Horizontal position absolute (G) 

Term, settable cmd char in prototype 
Cursor motion to row #1 col #2 (G) 

Down one line 
Home cursor (if no cup) 

Make cursor invisible 
Move cursor left one space. 

Memory relative cursor addressing (G) 

Make cursor appear normal (undo vs/vi) 
Non-destructive space (cursor right) 

Last line, first column (if no cup) 

Upline (cursor up) 

Make cursor very visible 
Delete character (*) 

Delete line (*) 

Disable status line 

Half-line down (forward 1/2 linefeed) 

Enable alternate char set 

Start alternate character set 

Turn on automatic margins 

Turn on blinking 

Turn on bold (extra bright) mode 

String to begin programs that use cup 

Delete mode (enter) 

Turn on half-bright mode 
Insert mode (enter); 

Turn on protected mode 

Turn on reverse video mode 

Turn on blank mode (chars invisible) 

Begin standout mode 
Start underscore mode 
Turn on xon/xoff handshaking 
Erase #1 characters (G) 

End alternate character set 
Turn off automatic margins 
Turn off all attributes 
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exit_ca_mode 


rmcup 


te 


String to end programs that use cup 


exitdeletemode 


rmdc 


ed 


End delete mode 


exitinsertmode 


rmir 


ei 


End insert mode; 


exitstandoutmode 


rmso 


se 


End standout mode 


exitunderlinemode 


rmul 


ue 


End underscore mode 


exitxonmode 


rmxon 


RX 


Turn off xon/xoff handshaking 


flashscreen 


flash 


vb 


Visible bell (may not move cursor) 


formfeed 


ff 


ff 


Hardcopy terminal page eject (*) 


fromstatusline 


fsl 


fs 


Return from status line 


initl string 


isl 


il 


Terminal initialization string 


init_2string 


is2 


is 


Terminal initialization string 


init_3string 


is3 


i3 


Terminal initialization string 


initfile 


if 


if 


Name of initialization file containing is 


initjDrog 


iprog 


iP 


Path name of program for init. 


insertcharacter 


ichl 


ic 


Insert character 


insertline 


ill 


al 


Add new blank line (*) 


insert_padding 


ip 


iP 


Insert pad after character inserted (*) 


keyal 


kal 


K1 


KEYAl, 0534, Upper left of keypad 


key_a3 


ka3 


K3 


KEYA3, 0535, Upper right of keypad 


key_b2 


kb2 


K2 


KEY B2, 0536, Center of keypad 


keybackspace 


kbs 


kb 


KEY BACKSPACE, 0407, Sent by backspace key 


key beg 


kbeg 


@1 


KEY BEG, 0542, Sent by beg(inning) key 


keybtab 


kcbt 


kB 


KEY_BTAB, 0541, Sent by back-tab key 


key cl 


kcl 


K4 


KEY Cl, 0537, Lower left of keypad 


key_c3 


kc3 


K5 


KEYC3, 0540, Lower right of keypad 


key cancel 


kcan 


@2 


KEYCANCEL, 0543, Sent by cancel key 


keycatab 


ktbc 


ka 


KEY CATAB, 0526, Sent by clear-all- tabs key 


key clear 


kclr 


kC 


KEY CLEAR, 0515, Sent by clear-screen or erase key 


keyclose 


kclo 


@3 


KEY CLOSE, 0544, Sent by close key 


keycommand 


kcmd 


@4 


KEY COMMAND, 0545, Sent by cmd (command) key 


key copy 


kcpy 


@5 


KEY COPY, 0546, Sent by copy key 


key create 


kcrt 


@6 


KEY CREATE, 0547, Sent by create key 


key_ctab 


kctab 


kt 


KEYCTAB, 0525, Sent by clear- tab key 


keydc 


kdchl 


kD 


KEY_DC, 0512, Sent by delete-character key 


key_dl 


kdll 


kL 


KEY DL, 0510, Sent by delete-line key 


key down 


kcudl 


kd 


KEYDOWN, 0402, Sent by terminal down-arrow key 


keyeic 


krmir 


kM 


KEY EIC, 0514, Sent by rmir or smir in insert mode 


key end 


kend 


@7 


KEY END, 0550, Sent by end key 


key enter 


kent 


@8 


KEY ENTER, 0527, Sent by enter/send key 


keyed 


kel 


kE 


KEY EOL, 0517, Sent by clear-to-end-of-line key 


keyeos 


ked 


kS 


KEY EOS, 0516, Sent by clear-to-end-of-screen key 


key_exit 


kext 


@9 


KEY EXIT, 0551, Sent by exit key 


keyfO 


kfO 


kO 


KEY_F(0), 0410, Sent by function key fO 


keyfl 


kfl 


kl 


KEY_F(1), 0411, Sent by function key fl 


key_f2 


kf2 


k2 


KEY_F(2), 0412, Sent by function key f2 


key_f3 


kf3 


k3 


KEY_F(3), 0413, Sent by function key f3 


key_f4 


kf4 


k4 


KEY_F(4), 0414, Sent by function key f4 


key_f5 


kf5 


k5 


KEY_F(5), 0415, Sent by function key f5 


key_f6 


kf6 


k6 


KEY_F(6), 0416, Sent by function key f6 
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key_f7 


kf7 


k7 


key_f8 


kf8 


k8 


key_f9 


kf9 


k9 


keyflO 


kflO 


k; 


key fll 


kfll 


Fl 


key_fl2 


kfl2 


F2 


key_fl3 


kfl3 


F3 


key_fl4 


kfl4 


F4 


key_fl5 


kfl5 


F5 


key_fl6 


kfl6 


F6 


key fl 7 


kfl7 


F7 


key_fl8 


kfl8 


F8 


key_fl9 


kfl9 


F9 


key_f20 


kf20 


FA 


key f21 


kf21 


FB 


key_f22 


kf22 


FC 


key_f23 


kf23 


FD 


key_f24 


kf24 


FE 


key_f25 


kf25 


FF 


key_f26 


kf26 


FG 


key_f27 


kf27 


FH 


key_f28 


kf28 


FI 


key_f29 


kf29 


FJ 


key_f30 


kf30 


FK 


key_f31 


kf31 


FL 


key_f32 


kf32 


FM 


key_f33 


kf33 


FN 


key_f34 


kf34 


FO 


key_f35 


kf35 


FP 


key_f36 


kf36 


FQ 


key_f37 


kf37 


FR 


key_f38 


kf38 


FS 


key_f39 


kf39 


FT 


key_f40 


kf40 


FU 


key_f41 


kf41 


FV 


key_f42 


kf42 


FW 


key_f43 


kf43 


FX 


key_f44 


kf44 


FY 


key_f45 


kf45 


FZ 


key_f46 


kf46 


Fa 


key f47 


kf47 


Fb 


key_f48 


kf48 


Fc 


key_f49 


kf49 


Fd 


key_f50 


kf50 


Fe 


key_f51 


kf51 


Ff 


key_f52 


kf52 


Fg 


key_f53 


kf53 


Fh 


key_f54 


kf54 


Fi 


key_f55 


kf55 


Fj 



KEYJF(7), 0417, Sent by function key f7 
KEY_F(8), 0420, Sent by function key f8 
KEY_F(9), 0421, Sent by function key f9 
KEY F(IO), 0422, Sent by function key flO 
KEY_F(11), 0423, Sent by function key fll 
KEY_F(12), 0424, Sent by function key fl2 
KEY_F(13), 0425, Sent by function key fl3 
KEY_F(14), 0426, Sent by function key fl4 
KEY_F(15), 0427, Sent by function key fl5 
KEY_F(16), 0430, Sent by function key fl6 
KEY_F(17), 0431, Sent by function key fl7 
KEY_F(18), 0432, Sent by function key fl8 
KEY_F(19), 0433, Sent by function key fl9 
KEY_F(20), 0434, Sent by function key f20 
KEY_F(21), 0435, Sent by function key f21 
KEY_F(22), 0436, Sent by function key f22 
KEY_F(23), 0437, Sent by function key f23 
KEY_F(24), 0440, Sent by function key f24 
KEY_F(25), 0441, Sent by function key f25 
KEY_F(26), 0442, Sent by function key f26 
KEY_F(27), 0443, Sent by function key f27 
KEY_F(28), 0444, Sent by function key f28 
KEY_F(29), 0445, Sent by function key f29 
KEY_F(30), 0446, Sent by function key f30 
KEY_F(31), 0447, Sent by function key f31 
KEY_F(32), 0450, Sent by function key f32 
KEY_F(13), 0451, Sent by function key fl3 
KEY_F(34), 0452, Sent by function key f34 
KEY_F(35), 0453, Sent by function key f35 
KEY_F(36), 0454, Sent by function key f36 
KEY_F(37), 0455, Sent by function key f37 
KEY_F(38), 0456, Sent by function key f38 
KEY_F(39), 0457, Sent by function key f39 
KEY_F(40), 0460, Sent by function key f40 
KEY_F(41), 0461, Sent by function key f41 
KEY_F(42), 0462, Sent by function key f42 
KEY_F(43), 0463, Sent by function key f43 
KEY_F(44), 0464, Sent by function key f44 
KEY_F(45), 0465, Sent by function key f45 
KEY_F(46), 0466, Sent by function key f46 
KEY_F(47), 0467, Sent by function key f47 
KEY_F(48), 0470, Sent by function key f48 
KEY_F(49), 0471, Sent by function key f49 
KEY_F(50), 0472, Sent by function key f50 
KEY_F(51), 0473, Sent by function key f51 
KEY_F(52), 0474, Sent by function key f52 
KEY_F(53), 0475, Sent by function key f53 
KEY_F(54), 0476, Sent by function key f54 
KEY_F(55), 0477, Sent by function key f55 
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key f56 


kf56 


Fk 


KEY_F(56), 0500, Sent by function key f56 


key_f57 


kf57 


FI 


KEY_F(57), 0501, Sent by function key f57 


key_f58 


kf58 


Fm 


KEY_F(58), 0502, Sent by function key f58 


key_f59 


kf59 


Fn 


KEY_F(59), 0503, Sent by function key f59 


key_f60 


kf60 


Fo 


KEY_F(60), 0504, Sent by function key f60 


key_f61 


kf61 


Fp 


KEY_F(61), 0505, Sent by function key f61 


key_f62 


kf62 


Fq 


KEY_F(62), 0506, Sent by function key f62 


key_f63 


kf63 


Fr 


KEY_F(63), 0507, Sent by function key f63 


key find 


kfnd 


@0 


KEY FIND, 0552, Sent by find key 


keyhelp 


khlp 


%1 


KEY HELP, 0553, Sent by help key 


keyhome 


khome 


kh 


KEY HOME, 0406, Sent by home key 


keyic 


kichl 


kl 


KEY IC, 0513, Sent by ins-char/enter ins-mode key 


keyil 


kill 


kA 


KEY_IL, 0511, Sent by insert-line key 


keyleft 


kcubl 


kl 


KEY LEFT, 0404, Sent by terminal left-arrow key 


keyil 


kll 


kH 


KEY_LL, 0533, Sent by home-down key 


keymark 


kmrk 


%2 


KEY_MARK, 0554, Sent by mark key 


key message 


kmsg 


%3 


KEY_MESSAGE, 0555, Sent by message key 


key_move 


kmov 


%4 


KEY_MOVE, 0556, Sent by move key 


key next 


knxt 


%5 


KEY NEXT, 0557, Sent by next-object key 


keynpage 


knp 


kN 


KEY NPAGE, 0522, Sent by next-page key 


key open 


kopn 


%6 


KEY OPEN, 0560, Sent by open key 


keyoptions 


kopt 


%7 


KEY OPTIONS, 0561, Sent by options key 


key_ppage 


kpp 


kP 


KEY PPAGE, 0523, Sent by previous-page key 


key_previous 


kprv 


%8 


KEY PREVIOUS, 0562, Sent by previous-object key 


key_print 


kprt 


%9 


KEY_PRINT, 0532, Sent by print or copy key 


key redo 


krdo 


%0 


KEY REDO, 0563, Sent by redo key 


key_reference 


kref 


&1 


KEY_REFERENCE, 0564, Sent by ref(erence) key 


key_refresh 


krfr 


&2 


KEY REFRESH, 0565, Sent by refresh key 


keyreplace 


krpl 


&3 


KEY_REPLACE, 0566, Sent by replace key 


keyrestart 


krst 


&4 


KEY RESTART, 0567, Sent by restart key 


key resume 


kres 


&5 


KEY_RESUME, 0570, Sent by resume key 


keyright 


kcufl 


kr 


KEY RIGHT, 0405, Sent by terminal right-arrow key 


key save 


ksav 


&6 


KEY_SAVE, 0571, Sent by save key 


keysbeg 


kBEG 


&9 


KEY SBEG, 0572, Sent by shifted beginning key 


keyscancel 


kCAN 


&0 


KEY_SCANCEL, 0573, Sent by shifted cancel key 


keyscommand 


kCMD 


*1 


KEY_SCOMMAND, 0574, Sent by shifted command key 


key_scopy 


kCPY 


*2 


KEY SCOPY, 0575, Sent by shifted copy key 


keyscreate 


kCRT 


*3 


KEY SCREATE, 0576, Sent by shifted create key 


keysdc 


kDC 


*4 


KEY_SDC, 0577, Sent by shifted delete-char key 


keysdl 


kDL 


*5 


KEY SDL, 0600, Sent by shifted delete-line key 


key_select 


kslt 


*6 


KEY_SELECT, 0601, Sent by select key 


key send 


kEND 


*7 


KEY_SEND, 0602, Sent by shifted end key 


keyseol 


kEOL 


*8 


KEY SEOL, 0603, Sent by shifted clear-line key 


keysexit 


kEXT 


*9 


KEY SEXIT, 0604, Sent by shifted exit key 


key_sf 


kind 


kF 


KEY SF, 0520, Sent by scroll-forward/down key 


keysfind 


kFND 


*0 


KEY SFIND, 0605, Sent by shifted find key 


keyshelp 


kHLP 


#1 


KEY SHELP, 0606, Sent by shifted help key 


keyshome 


kHOM 


#2 


KEY SHOME, 0607, Sent by shifted home key 


key sic 


kIC 


#3 


KEY SIC, 0610, Sent by shifted input key 
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k e y_slcft 

keysmessage 

keysmove 

key_snext 

keysoptions 

k e y_sp rev i° us 

keysprint 

keysr 

keysredo 

keysreplace 

keysright 

keysrsume 

keyssave 

key_ssuspend 

keystab 

keysundo 

keysuspend 

key_undo 

key_up 

keypad_local 

keypad_xmit 

labfO 

labfl 

lab_f2 

lab_f3 

lab_f4 

lab_f5 

lab_f6 

lab J7 

lab_f8 

lab_f9 

labflO 

labeloff 

label jon 

meta_off 

metaon 

newline 

padchar 

parmdch 

parm_delete_line 

parmdowncursor 

parmich 

parm index 

parminsertline 

parmleftcursor 

parmrightcursor 

parmrindex 

parmupcursor 

pkeykey 
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kLFT 


#4 


KEYSLEFT, 0611, Sent by shifted left-arrow key 


kMSG 


%a 


KEY SMESSAGE, 0612, Sent by shifted message key 


kMOV 


%b 


KEY_SMOVE, 0613, Sent by shifted move key 


kNXT 


%c 


KEYSNEXT, 0614, Sent by shifted next key 


kOPT 


%d 


KEYSOPTIONS, 0615, Sent by shifted options key 


kPRV 


%e 


KEY SPREVIOUS, 0616, Sent by shifted prev key 


kPRT 


%f 


KEY_SPRINT, 0617, Sent by shifted print key 


kri 


kR 


KEY SR, 0521, Sent by scroll-backward/up key 


kRDO 


%g 


KEY SREDO, 0620, Sent by shifted redo key 


kRPL 


%h 


KEY SREPLACE, 0621, Sent by shifted replace key 


kRIT 


%i 


KEY SRIGHT, 0622, Sent by shifted right-arrow key 


kRES 


%j 


KEY_SRSUME, 0623, Sent by shifted resume key 


kSAV 


!1 


KEY_SSAVE, 0624, Sent by shifted save key 


kSPD 


!2 


KEYSSUSPEND, 0625, Sent by shifted suspend key 


khts 


kT 


KEY_STAB, 0524, Sent by set- tab key 


kUND 


!3 


KEY_SUNDO, 0626, Sent by shifted undo key 


kspd 


&7 


KEY SUSPEND, 0627, Sent by suspend key 


kund 


&8 


KEYJJNDO, 0630, Sent by undo key 


kcuul 


ku 


KEYJUP, 0403, Sent by terminal up-arrow key 


rmkx 


ke 


Out of "keypad- transmit" mode 


smkx 


ks 


Put terminal in "keypad-transmit" mode 


lfO 


10 


Labels on function key fO if not fO 


lfl 


11 


Labels on function key fl if not fl 


lf2 


12 


Labels on function key f2 if not f2 


lf3 


13 


Labels on function key f3 if not f3 


lf4 


14 


Labels on function key f4 if not f4 


lf5 


15 


Labels on function key f5 if not f5 


lf6 


16 


Labels on function key f6 if not f6 


lf7 


17 


Labels on function key f7 if not f7 


lf8 


18 


Labels on function key f8 if not f8 


lf9 


19 


Labels on function key f9 if not f9 


lflO 


la 


Labels on function key flO if not flO 


rmln 


LF 


Turn off soft labels 


smln 


LO 


Turn on soft labels 


rmm 


mo 


Turn off ''meta mode” 


smm 


mm 


Turn on "meta mode" (8th bit) 


nel 


nw 


Newline (behaves like cr followed by If) 


pad 


pc 


Pad character (rather than null) 


dch 


DC 


Delete #1 chars (G*) 


dl 


DL 


Delete #1 lines (G*) 


cud 


DO 


Move cursor down #1 lines. (G*) 


ich 


IC 


Insert #1 blank chars (G*) 


indn 


SF 


Scroll forward #1 lines. (G) 


il 


AL 


Add #1 new blank lines (G*) 


cub 


LE 


Move cursor left #1 spaces (G) 


cuf 


RI 


Move cursor right #1 spaces. (G*) 


rin 


SR 


Scroll backward #1 lines. (G) 


cuu 


UP 


Move cursor up #1 lines. (G*) 


pfkey 


pk 


Prog funct key #1 to type string #2 
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pkeylocal 


pfloc 


Pi 


Prog funct key #1 to execute string #2 


pkeyxmit 


pfx 


px 


Prog funct key #1 to xmit string #2 


plabnorm 


pin 


pn 


Prog label #1 to show string #2 


printscreen 


mcO 


ps 


Print contents of the screen 


prtrnon 


mc5p 


pO 


Turn on the printer for #1 bytes 


prtroff 


mc4 


Pf 


Turn off the printer 


prtr_on 


mc5 


po 


Turn on the printer 


repeatchar 


rep 


rp 


Repeat char #1 #2 times (G*) 


reqforinput 


rfi 


RF 


Send next input char (for ptys) 


resetl string 


rsl 


rl 


Reset terminal completely to sane modes 


reset_2string 


rs2 


r2 


Reset terminal completely to sane modes 


reset_3string 


rs3 


r3 


Reset terminal completely to sane modes 


reset file 


rf 


rf 


Name of file containing reset string 


restorecursor 


rc 


rc 


Restore cursor to position of last sc 


rowaddress 


vpa 


cv 


Vertical position absolute (G) 


save_cursor 


sc 


sc 


Save cursor position. 


scroll_forward 


ind 


sf 


Scroll text up 


scrollreverse 


ri 


sr 


Scroll text down 


set_attributes 


sgr 


sa 


Define the video attributes #l-#9 (G) 


set_left_margin 


smgl 


ML 


Set soft left margin 


set_right_margin 


smgr 


MR 


Set soft right margin 


set_tab 


hts 


st 


Set a tab in all rows, current column. 


setwindow 


wind 


wi 


Current window is lines #l-#2 cols #3-#4 (G) 


tab 


ht 


ta 


Tab to next 8 space hardware tab stop. 


tojstatusline 


tsl 


ts 


Go to status line, col #1 (G) 


underlinechar 


uc 


uc 


Underscore one char and move past it 


uphalfline 


hu 


hu 


Half-line up (reverse 1 /2 linefeed) 


xoffcharacter 


xoffc 


XF 


X-off character 


xon character 


xonc 


XN 


X-on character 



SAMPLE ENTRY 

The following entry, which describes the Concept — 100 terminal, is among the 
more complex entries in the terminfo file as of this writing. 
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concept 100 ! clOOl concept ! c104 ! c100-4p! concept 100, 
am, db , eo, in, mir, ul , xenl , 
cols#80, lines#24, pb#9600, vt#8, 
bel = /v G, blank=\EH, blink = \EC, clear= A L$<2*> , 
cnorm = \Ew, cr = /v M$<9>, cub1 = A H, cud1 = ~J, 
cuf 1 =\E= , cup = \Ea%p 1 % / * %+%c%p2% ' ' % + %c , 

cuu1=\E; , cvvis = \EW, dchl =\E~A$< 1 6*> , dim = \EE, 
dl 1=\E"B$<3*> , ed = \E"C$< 16*> , e 1 = \E "U$ < 1 6 > , 
f lash = \Ek$<2 0>\EK, ht = \t$<8> , il 1 =\E~R$<3*> , 
ind =/v J, . ind = yv J$<9> , ip=$<16*>, 

is2=\EU\Ef \E7\E5\E8\El\ENH\EK\E\0\Eo&\0\Eo\47\E , 
kbs= A h, kcub1=\E>, kcud1=\E<, kcuf1=\E=, kcuu1=\E; , 
kf 1 =\E5 , kf 2 = \E6 , kf3 = \E7, khome = \E?, 
prot=\EI, r ep=\Er%p 1 %c%p2% / / %+%c$<.2*>, 

rev=\ED , rmcup=\Ev\s\s\s\s$<6>\Ep\r\n , 
rmir=\E\0, rmkx=\Ex, rmso=\Ed\Ee, rmul=\Eg, 
rmul=\Eg, sgr0=\EN\0, smcup=\EU\Ev\s\s8p\Ep\r , 
smir=\E A P, smkx=\EX, smso=\EE\ED, smul=\EG, 

Entries may continue onto multiple lines by placing white space at the beginning 
of each line except the first. Lines beginning with are taken as comment 
lines. Capabilities in terminfo are of three types: boolean capabilities which indi- 
cate that the terminal has some particular feature, numeric capabilities giving the 
size of the terminal or particular features, and string capabilities, which give a 
sequence which can be used to perform particular terminal operations. 

Types of Capabilities 

All capabilities have names. For instance, the fact that the Concept has automatic 
margins (i.e., an automatic return and linefeed when the end of a line is reached) 
is indicated by the capability am. Hence the description of the Concept includes 
am. Numeric capabilities are followed by the character '#' and then the value. 
Thus cols, which indicates the number of columns the terminal has, gives the 
value 80 for the Concept. The value may be specified in decimal, octal or hexa- 
decimal using normal C conventions. 

Finally, string-valued capabilities, such as el (clear to end of line sequence) are 
given by the two- to five-character capname, an '=', and then a string ending at 
the next following comma. A delay in milliseconds may appear anywhere in 
such a capability, enclosed in $<..> brackets, as in el=*\EK$<3>, and padding 
characters are supplied by tputs() (see curses( 3X)) to provide this delay. The 
delay can be either a number, e.g., 20, or a number followed by an (i.e., 3*), a 
'/' (i.e., 5/), or both (i.e., 10*/). A '*' indicates that the padding required is pro- 
portional to the number of lines affected by the operation, and the amount given 
is the per-affected-unit padding required. (In the case of insert character, the 
factor is still the number of lines affected. This is always one unless the ter- 
minal has in and the software uses it.) When a is specified, it is sometimes 
useful to give a delay of the form 3.5 to specify a delay per unit to tenths of mil- 
liseconds. (Only one decimal place is allowed.) A '/' indicates that the padding 
is mandatory. Otherwise, if the terminal has xon defined, the padding informa- 
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tion is advisory and will only be used for cost estimates or when the terminal is 
in raw mode. Mandatory padding will be transmitted regardless of the setting of 

xon. 

A number of escape sequences are provided in the string valued capabilities for 
easy encoding of characters there. Both \E and \e map to an ESCAPE character, 
*x maps to a control — x for any appropriate x, and the sequences \n, \1, \r, \t, \b, 
\f, and \s give a newline, linefeed, return, tab, backspace, formfeed, and space, 
respectively. Other escapes include: \ A for caret Q; \\ for backslash (\); \, for 
comma (,); \: for colon (:); and \0 for null. (\0 will actually produce \200, which 
does not terminate a string but behaves as a null character on most terminals.) 
Finally, characters may be given as three octal digits after a backslash (e.g., 
\123). 

Sometimes individual capabilities must be commented out. To do this, put a 
period before the capability name. For example, see the second ind in the 
example above. Note that capabilities are defined in a left-to-right order and, 
therefore, a prior definition will override a later definition. 

Preparing Descriptions 

The most effective way to prepare a terminal description is by imitating the 
description of a similar terminal in terminfo and to build up a description gradu- 
ally, using partial descriptions with vi(l) to check that they are correct. Be 
aware that a very unusual terminal may expose deficiencies in the ability of the 
terminfo file to describe it or the inability of vi(l) to work with that terminal. 
To test a new terminal description, set the environment variable TERMINFO to a 
pathname of a directory containing the compiled description you are working on 
and programs will look there rather than in /usr/ lib /terminfo. To get the pad- 
ding for insert-line correct (if the terminal manufacturer did not document it) a 
severe test is to comment out xon, edit a large file at 9600 baud with vi(l), 
delete 16 or so lines from the middle of the screen, then hit the u key several 
times quickly. If the display is corrupted, more padding is usually needed. A 
similar test can be used for insert-character. 

Basic Capabilities 

The number of columns on each line for the terminal is given by the cols 
numeric capability. If the terminal has a screen, then the number of lines on the 
screen is given by the lines capability. If the terminal wraps around to the 
beginning of the next line when it reaches the right margin, then it should have 
the am capability. If the terminal can clear its screen, leaving the cursor in the 
home position, then this is given by the clear string capability. If the terminal 
overstrikes (rather than clearing a position when a character is struck over) then 
it should have the os capability. If the terminal is a printing terminal, with no 
soft copy unit, give it both he and os. (os applies to storage scope terminals, 
such as Tektronix 4010 series, as well as hard-copy and APL terminals.) If there 
is a code to move the cursor to the left edge of the current row, give this as cr. 
(Normally this will be carriage return, control M.) If there is a code to produce 
an audible signal (bell, beep, etc) give this as bel. If the terminal uses the xon- 
xoff flow-control protocol, like most terminals, specify xon. 

If there is a code to move the cursor one position to the left (such as backspace) 
that capability should be given as cubl. Similarly, codes to move to the right. 
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up, and down should be given as cufl, cuul, and cudl. These local cursor 
motions should not alter the text they pass over; for example, you would not 
normally use "cufl=\s" because the space would erase the character moved 
over. 

A very important point here is that the local cursor motions encoded in terminfo 
are undefined at the left and top edges of a screen terminal. Programs should 
never attempt to backspace around the left edge, unless bw is given, and should 
never attempt to go up locally off the top. In order to scroll text up, a program 
will go to the bottom left corner of the screen and send the ind (index) string. 

To scroll text down, a program goes to the top left corner of the screen and 
sends the ri (reverse index) string. The strings ind and ri are undefined when 
not on their respective corners of the screen. 

Parameterized versions of the scrolling sequences are indn and rin which have 
the same semantics as ind and ri except that they take one parameter, and scroll 
that many lines. They are also undefined except at the appropriate edge of the 
screen. 

The am capability tells whether the cursor sticks at the right edge of the screen 
when text is output, but this does not necessarily apply to a cufl from the last 
column. The only local motion which is defined from the left edge is if bw is 
given, then a cubl from the left edge will move to the right edge of the previous 
row. If bw is not given, the effect is undefined. This is useful for drawing a box 
around the edge of the screen, for example. If the terminal has switch selectable 
automatic margins, the terminfo file usually assumes that this is on; i.e., am. If 
the terminal has a command which moves to the first column of the next line, 
that command can be given as nel (newline). It does not matter if the command 
clears the remainder of the current line, so if the terminal has no cr and If it 
may still be possible to craft a working nel out of one or both of them. 

These capabilities suffice to describe hardcopy and screen terminals. Thus the 
model 33 teletype is described as 

33|tty33|tty|model 33 teletype, bel= A G, cols# 72, cr= A M, cudl= A J, he, 

ind= A J, os, 

while the Lear Siegler ADM— 3 is described as 

adm3|lsi adm3, am, bel= A G, clear= A Z, cols# 80, cr= A M, cubl— A H, 

cudl= A J, ind= A j, lines# 24, 

Parameterized Strings 

Cursor addressing and other strings requiring parameters in the terminal are 
described by a parameterized string capability, with printf(3S)-like escapes (%x) 
in it. For example, to address the cursor, the cup capability is given, using two 
parameters: the row and column to address to. (Rows and columns are num- 
bered from zero and refer to the physical screen visible to the user, not to any 
unseen memory.) If the terminal has memory relative cursor addressing, that can 
be indicated by mrcup. 

The parameter mechanism uses a stack and special */' codes to manipulate it in 
the manner of a Reverse Polish Notation (postB calculator. Typically a 
sequence will push one of the parameters onto th< tack and then print it in 
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some format. Often more complex operations are necessary. Binary operations 
are in postfix form with the operands in the usual order. That is, to get x— 5 one 
would use %gx% {5} % — . 

The % encodings have the following meanings: 

%% outputs '%' 

%[[:]jlags][width[.precision]][doxXs] 

as in printf, flags are [ — t-#] and space 
print pop() gives %c 



%c 

%p[l-9] 

%P[a-z] 

%g[a-z] 

%'c' 

%{nn} 

%1 



push parm 
set variable [a-z] to pop() 
get variable [a-z] and push it 
push char constant c 
push decimal constant nn 
push strlen(pop()) 



%+ %- %* %/ %m 

arithmetic (%m is mod): push(pop() op pop()) 
bit operations: push(pop() op pop()) 
logical operations: push(pop() op pop()) 
logical operations: and, or 
unary operations: push(op pop()) 

(for ANSI terminals) 
add 1 to first parm, if one parm present, 
or first two parms, if more than one parm present 



%& %| % A 
%= %> %< 
%A %0 
%! %~ 

%i 



%? expr %t thenpart %e elsepart %; 

if-then-else, %e elsepart is optional; 
else-if's are possible ala Algol 68: 

%? c %t b %e c %t b %e c %t b %e c %t b %e b %; 

A -a . fk |« J J TT TC O 

c. are conditions, 5. are bodies. 

1 1 

If the " flag is used with // %[doxXs] ,/ , then a colon (:) must be placed between 
the "%" and the to differentiate the flag from the binary operator, 

.e.g 16.16s". 

Consider the Hewlett-Packard 2645, which, to get to row 3 and column 12, 
needs to be sent \E&al2c03Y padded for 6 milliseconds. Note that the order 
of the rows and columns is inverted here, and that the row and column are 
zero-padded as two digits. Thus its cup capability is 
// cup=\E&a%p2%2.2dc%pl %2.2dY$ < 6 > ". 

The Micro-Term ACT-IV needs the current row and column sent preceded by a 
A T, with the row and column simply encoded in binary, 
// cup= A T%pl%c%p2%c". Terminals which use "^oc" need to be able to back- 
space the cursor (cubl), and to move the cursor up one line on the screen 
(cuul). This is necessary because it is not always safe to transmit \n, A D, and \r, 
as the system may change or discard them. (The library routines dealing with 
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terminfo set tty modes so that tabs are never expanded, so \t is safe to send. 
This turns out to be essential for the Ann Arbor 4080.) 

A final example is the LSI ADM-3a, which uses row and column offset by a blank 
character, thus // cup=\E=%pl%'\s , %+%c%p2% , \s , %+%c". After sending 
"YE*", this pushes the first parameter, pushes the ASCII value for a space (32), 
adds them (pushing the sum on the stack in place of the two previous values), 
and outputs that value as a character. Then the same is done for the second 
parameter. More complex arithmetic is possible using the stack. 

Cursor Motions 

If the terminal has a fast way to home the cursor (to very upper left corner of 
screen) then this can be given as home; similarly a fast way of getting to the 
lower left-hand corner can be given as 11; this may involve going up with cuul 
from the home position, but a program should never do this itself (unless 11 
does) because it can make no assumption about the effect of moving up from 
the home position. Note that the home position is the same as addressing to 
(0,0): to the top left corner of the screen, not of memory. (Thus, the \EH 
sequence on Hewlett-Packard terminals cannot be used for home without losing 
some of the other features on the terminal.) 

If the terminal has row or column absolute-cursor addressing, these can be given 
as single parameter capabilities hpa (horizontal position absolute) and vpa (vert- 
ical position absolute). Sometimes these are shorter than the more general two- 
parameter sequence (as with the Hewlett-Packard 2645) and can be used in 
preference to cup. If there are parameterized local motions (e.g., move n spaces 
to the right) these can be given as cud, cub, cuf, and cuu with a single param- 
eter indicating how many spaces to move. These are primarily useful if the ter- 
minal does not have cup, such as the Tektronix 4025. 

Area Clears 

If the terminal can clear from the current position to the end of the line, leaving 
the cursor where it is, this should be given as el. If the terminal can clear from 
the beginning of the line to the current position inclusive, leaving the cursor 
where it is, this should be given as ell. If the terminal can clear from the 
current position to the end of the display, then this should be given as ed. ed is 
only defined from the first column of a line. (Thus, it can be simulated by a 
request to delete a large number of lines, if a true ed is not available.) 

Insert/delete line 

If the terminal can open a new blank line before the line where the cursor is, 
this should be given as ill; this is done only from the first position of a line. 
The cursor must then appear on the newly blank line. If the terminal can delete 
the line which the cursor is on, then this should be given as dll; this is done 
only from the first position on the line to be deleted. Versions of ill and dll 
which take a single parameter and insert or delete that many lines can be given 
as il and dl. 

If the terminal has a settable destructive scrolling region (like the VT100) the 
command to set this can be described with the csr capability, which takes two 
parameters: the top and bottom lines of the scrolling region. The cursor position 
is, alas, undefined after using this command. It is possible to get the effect of 
insert or delete line using this command -- the sc and rc (save and restore 
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cursor) commands are also useful. Inserting lines at the top or bottom of the 
screen can also be done using ri or ind on many terminals without a true 
insert/delete line, and is often faster even on terminals with those features. 

To determine whether a terminal has destructive scrolling regions or non- 
destructive scrolling regions, create a scrolling region in the middle of the screen, 
place data on the bottom line of the scrolling region, move the cursor to the top 
line of the scrolling region, and do a reverse index (ri) followed by a delete line 
(dll) or index (ind). If the data that was originally on the bottom line of the 
scrolling region was restored into the scrolling region by the dll or ind, then the 
terminal has non-destructive scrolling regions. Otherwise, it has destructive 
scrolling regions. Do not specify csr if the terminal has non-destructive scrolling 
regions, unless ind, ri, indn, rin, dl, and dll all simulate destructive scrolling. 

If the terminal has the ability to define a window as part of memory, which all 
commands affect, it should be given as the parameterized string wind. The four 
parameters are the starting and ending lines in memory and the starting and 
ending columns in memory, in that order. 

If the terminal can retain display memory above, then the da capability should 
be given; if display memory can be retained below, then db should be given. 
These indicate that deleting a line or scrolling a full screen may bring non-blank 
lines up from below or that scrolling back with ri may bring down non-blank 
lines. 

Insert/Delete Character 

There are two basic kinds of intelligent terminals with respect to insert/delete 
character operations which can be described using terminfo. The most common 
insert/delete character operations affect only the characters on the current line 
and shift characters off the end of the line rigidly. Other terminals, such as the 
Concept 100 and the Perkin Elmer Owl, make a distinction between typed and 
untyped blanks on the screen, shifting upon an insert or delete only to an 
untyped blank on the screen which is either eliminated, or expanded to two 
untyped blanks. You can determine the kind of terminal you have by clearing 
the screen and then typing text separated by cursor motions. Type "abc def" 
using local cursor motions (not spaces) between the abc and the def. Then posi- 
tion the cursor before the abc and put the terminal in insert mode. If typing 
characters causes the rest of the line to shift rigidly and characters to fall off the 
end, then your terminal does not distinguish between blanks and untyped posi- 
tions. If the abc shifts over to the def which then move together around the 
end of the current line and onto the next as you insert, you have the second 
type of terminal, and should give the capability in, which stands for "insert 
null". While these are two logically separate attributes (one line versus multiline 
insert mode, and special treatment of untyped spaces) we have seen no termi- 
nals whose insert mode cannot be described with the single attribute. 

terminfo can describe both terminals which have an insert mode and terminals 
which send a simple sequence to open a blank position on the current line. 
Give as smir the sequence to get into insert mode. Give as rmir the sequence 
to leave insert mode. Now give as ichl any sequence needed to be sent just 
before sending the character to be inserted. Most terminals with a true insert 
mode will not give ichl; terminals which send a sequence to open a screen 
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position should give it here. (If your terminal has both, insert mode is usually 
preferable to ichl. Do not give both unless the terminal actually requires both 
to be used in combination.) If post-insert padding is needed, give this as a 
number of milliseconds padding in ip (a string option). Any other sequence 
which may need to be sent after an insert of a single character may also be 
given in ip. If your terminal needs both to be placed into an 'insert mode' and a 
special code to precede each inserted character, then both smir/rmir and ichl 
can be given, and both will be used. The ich capability, with one parameter, n, 
will repeat the effects of ichl n times. 

If padding is necessary between characters typed while not in insert mode, give 
this as a number of milliseconds padding in rmp. 

It is occasionally necessary to move around while in insert mode to delete char- 
acters on the same line (e.g., if there is a tab after the insertion position). If your 
terminal allows motion while in insert mode you can give the capability mir to 
speed up inserting in this case. Omitting mir will affect only speed. Some ter- 
minals (notably Datamedia's) must not have mir because of the way their insert 
mode works. 

Finally, you can specify dchl to delete a single character, dch with one param- 
eter, n, to delete n characters, and delete mode by giving smdc and rmdc to 
enter and exit delete mode (any mode the terminal needs to be placed in for 
dchl to work). 

A command to erase n characters (equivalent to outputting n blanks without 
moving the cursor) can be given as ech with one parameter. 

Highlighting, Underlining, and Visible Bells 

If your terminal has one or more kinds of display attributes, these can be 
represented in a number of different ways. You should choose one display form 
as standout mode (see curses( 3X)), representing a good, high contrast, easy-on- 
the-eyes, format for highlighting error messages and other attention getters. (If 
you have a choice, reverse-video plus half-bright is good, or reverse-video alone; 
however, different users have different preferences on different terminals.) The 
sequences to enter and exit standout mode are given as smso and rmso, respec- 
tively. If the code to change into or out of standout mode leaves one or even 
two blank spaces on the screen, as the TVI 912 and Teleray 1061 do, then xmc 
should be given to tell how many spaces are left. 

Codes to begin underlining and end underlining can be given as smul and rmul 
respectively. If the terminal has a code to underline the current character and 
move the cursor one space to the right, such as the Micro-Term MIME, this can 
be given as uc. 

Other capabilities to enter various highlighting modes include blink (blinking), 
bold (bold or extra-bright), dim (dim or half-bright), invis (blanking or invisible 
text), prot (protected), rev (reverse-video), sgrO (turn off all attribute modes), 
smacs (enter alternate-character-set mode), and rmacs (exit alternate-character- 
set mode). Turning on any of these modes singly may or may not turn off other 
modes. If a command is necessary before alternate character set mode is 
entered, give the sequence in enacs (enable alternate-character-set mode). 
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If there is a sequence to set arbitrary combinations of modes, this should be 
given as sgr (set attributes), taking nine parameters. Each parameter is either 0 
or non-zero, as the corresponding attribute is on or off. The nine parameters 
are, in order: standout, underline, reverse, blink, dim, bold, blank, protect, alter- 
nate character set. Not all modes need be supported by sgr, only those for 
which corresponding separate attribute commands exist. (See the example at the 
end of this section.) 

Terminals with the "magic cookie" glitch (xmc) deposit special "cookies" when 
they receive mode-setting sequences, which affect the display algorithm rather 
than having extra bits for each character. Some terminals, such as the Hewlett- 
Packard 2621, automatically leave standout mode when they move to a new line 
or the cursor is addressed. Programs using standout mode should exit standout 
mode before moving the cursor or sending a newline, unless the msgr capa- 
bility, asserting that it is safe to move in standout mode, is present. 

If the terminal has a way of flashing the screen to indicate an error quietly (a 
bell replacement), then this can be given as flash; it must not move the cursor. 
A good flash can be done by changing the screen into reverse video, pad for 200 
ms, then return the screen to normal video. 

If the cursor needs to be made more visible than normal when it is not on the 
bottom line (to make, for example, a non-blinking underline into an easier to 
find block or blinking underline) give this sequence as cvvis. The boolean chts 
should also be given. If there is a way to make the cursor completely invisible, 
give that as civis. The capability cnorm should be given which undoes the 
effects of either of these modes. 

If the terminal needs to be in a special mode when running a program that uses 
these capabilities, the codes to enter and exit this mode can be given as smcup 
and rmcup. This arises, for example, from terminals like the Concept with more 
than one page of memory. If the terminal has only memory relative cursor 
addressing and not screen relative cursor addressing, a one screen-sized window 
must be fixed into the terminal for cursor addressing to work properly. This is 
also used for the Tektronix 4025, where smcup sets the command character to 
be the one used by terminfo. If the smcup sequence will not restore the screen 
after an rmcup sequence is output (to the state prior to outputting rmcup), 
specify nrrmc. 

If your terminal generates underlined characters by using the underline character 
(with no special codes needed) even though it does not otherwise overstrike 
characters, then you should give the capability ul. For terminals where a char- 
acter overstriking another leaves both characters on the screen, give the capa- 
bility os. If overstrikes are erasable with a blank, then this should be indicated 
by giving eo. 

Example of highlighting: assume that the terminal under question needs the fol- 
lowing escape sequences to turn on various modes. 
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tparm 


attribute 


escape sequence 


parameter 


none 


\E[0m 


pi 


standout 


\E[0;4;7m 


P2 


underline 


\E[0;3m 


p3 


reverse 


\E[0;4m 


p4 


blink 


\E[0;5m 


p5 


dim 


\E[0;7m 


p6 


bold 


\E[0;3;4m 


P7 


invis 


\E[0;8m 


p8 


protect 


not available 


p9 


altcharset 


“O (off) 'N(on) 



Note that each escape sequence requires a 0 to turn off other modes before 
turning on its own mode. Also note that, as suggested above, standout is set up 
to be the combination of reverse and dim. Also, since this terminal has no bold 
mode, bold is set up as the combination of reverse and underline. In addition, to 
allow combinations, such as underline+blink, the sequence to use would be 
\E[0;3;5m. The terminal doesn't have protect mode, either, but that cannot be 
simulated in any way, so p8 is ignored. The altcharset mode is different in that 
it is either a O or A N depending on whether it is off or on. If all modes were to 
be turned on, the sequence would be \E[0;3;4;5;7;8m A N. 

Now look at when different sequences are output. For example, ;3 is output 
when either p2 or p6 is true, that is, if either underline or bold modes are turned 
on. Writing out the above sequences, along with their dependencies, gives the 



following: 






sequence 


when to output 


terminfo translation 


\E[0 


always 


\E[0 


;3 


if p2 or p6 


%?%p2%p6%|%t;3%; 


; 4 


if pi or p3 or p6 


% ? % p 1 % p 3 % p/o p 6 % p/o t ; 4 % ; 


;5 


if p4 


%?%p4%t;5%; 


;7 


if pi or p5 


%?%pl %p5%|%t;7%; 


;8 


if p7 


%?%p7%t;8%; 


m 


always 


m 


“N or ‘O 


if p9 A N, else a O 


%?%p9%t"N%e , '0%; 



Putting this all together into the sgr sequence gives: 

sgr =\E [0 % ? % p 2 % p 6 % p/o t; 3 % ; % ? % p 1 % p 3 % |% p 6 % |% t; 4 % ; % ? % p5 % t;5 % ; % ? % p 1 % p5 % 
p/o t ; 7 % ; % ? % p 7 % t ; 8 % ; m % ? % p 9 % t A N % e A O % ; , 

Keypad 

If the terminal has a keypad that transmits codes when the keys are pressed, this 
information can be given. Note that it is not possible to handle terminals where 
the keypad only works in local (this applies, for example, to the unshifted 
Hewlett-Packard 2621 keys). If the keypad can be set to transmit or not 
transmit, give these codes as smkx and rmkx. Otherwise the keypad is assumed 
to always transmit. 
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The codes sent by the left arrow, right arrow, up arrow, down arrow, and home 
keys can be given as kcubl, kcufl, kcuul, kcudl, and khome respectively. If 
there are function keys such as fO, fl, ..., f63, the codes they send can be given 
as kfO, kfl, kf63. If the first 11 keys have labels other than the default fO 
through flO, the labels can be given as lfO, Ifl, IflO. The codes transmitted 
by certain other special keys can be given: kll (home down), kbs (backspace), 
ktbc (clear all tabs), kctab (clear the tab stop in this column), kclr (clear screen 
or erase key), kdchl (delete character), kdll (delete line), krmir (exit insert 
mode), kel (clear to end of line), ked (clear to end of screen), kichl (insert char- 
acter or enter insert mode), kill (insert line), knp (next page), kpp (previous 
page), kind (scroll forward/down), kri (scroll backward/up), khts (set a tab stop 
in this column). In addition, if the keypad has a 3 by 3 array of keys including 
the four arrow keys, the other five keys can be given as kal, ka3, kb2, kcl, and 
kc3. These keys are useful when the effects of a 3 by 3 directional pad are 
needed. Further keys are defined above in the capabilities list. 

Strings to program function keys can be given as pfkey, pfloc, and pfx. A string 
to program their soft-screen labels can be given as pin. Each of these strings 
takes two parameters: the function key number to program (from 0 to 10) and 
the string to program it with. Function key numbers out of this range may pro- 
gram undefined keys in a terminal-dependent manner. The difference between 
the capabilities is that pfkey causes pressing the given key to be the same as the 
user typing the given string; pfloc causes the string to be executed by the ter- 
minal in local mode; and pfx causes the string to be transmitted to the computer. 
The capabilities nlab, lw and lh define how many soft labels there are and their 
width and height. If there are commands to turn the labels on and off, give 
them in smln and rmln. smln is normally output after one or more pin 
sequences to make sure that the change becomes visible. 

Tabs and Initialization 

If the terminal has hardware tabs, the command to advance to the next tab stop 
can be given as ht (usually control I). A "backtab" command which moves left- 
ward to the next tab stop can be given as cbt. By convention, if the teletype 
modes indicate that tabs are being expanded by the computer rather than being 
sent to the terminal, programs should not use ht or cbt even if they are present, 
since the user may not have the tab stops properly set. If the terminal has 
hardware tabs which are initially set every n spaces when the terminal is 
powered up, the numeric parameter it is given, showing the number of spaces 
the tabs are set to. This is normally used by tput init (see tput( 1)) to determine 
whether to set the mode for hardware tab expansion and whether to set the tab 
stops. If the terminal has tab stops that can be saved in nonvolatile memory, 
the terminfo description can assume that they are properly set. If there are com- 
mands to set and clear tab stops, they can be given as tbc (clear all tab stops) 
and hts (set a tab stop in the current column of every row). 

Other capabilities include: isl, is2, and is3, initialization strings for the terminal; 
iprog, the path name of a program to be run to initialize the terminal; and if, 
the name of a file containing long initialization strings. These strings are 
expected to set the terminal into modes consistent with the rest of the terminfo 
description. They must be sent to the terminal each time the user logs in and be 
output in the following order: run the program iprog; output isl; output is2; set 
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the margins using mgc, smgl and smgr; set the tabs using tbc and hts; print the 
file if; and finally output is3. This is usually done using the init option of 
tput( 1); see profile (4). 

Most initialization is done with is2. Special terminal modes can be set up 
without duplicating strings by putting the common sequences in is2 and special 
cases in isl and is3. Sequences that do a harder reset from a totally unknown 
state can be given as rsl, rs2, rf, and rs3, analogous to isl, is2, is3, and if. (The 
method using files, if and rf, is used for a few terminals, from /usr/lib/tabset/*; 
however, the recommended method is to use the initialization and reset strings.) 
These strings are output by tput reset, which is used when the terminal gets 
into a wedged state. Commands are normally placed in rsl, rs2, rs3, and rf only 
if they produce annoying effects on the screen and are not necessary when log- 
ging in. For example, the command to set a terminal into 80-column mode 
would normally be part of is2, but on some terminals it causes an annoying 
glitch on the screen and is not normally needed since the terminal is usually 
already in 80 -column mode. 

If a more complex sequence is needed to set the tabs than can be described by 
using tbc and hts, the sequence can be placed in is2 or if. 

If there are commands to set and clear margins, they can be given as mgc (clear 
all margins), smgl (set left margin), and smgr (set right margin). 

Delays 

Certain capabilities control padding in the tty(7) driver. These are primarily 
needed by hard-copy terminals, and are used by tput init to set tty modes 
appropriately. Delays embedded in the capabilities cr, ind, cubl, ff, and tab can 
be used to set the appropriate delay bits to be set in the tty driver. If pb (pad- 
ding baud rate) is given, these values can be ignored at baud rates below the 
value of pb. 

Status Lines 

If the terminal has an extra "status line" that is not normally used by software, 
this fact can be indicated. If the status line is viewed as an extra line below the 
bottom line, into which one can cursor address normally (such as the Heathkit 
hl9's 25th line, or the 24th line of a VT100 which is set to a 23-line scrolling 
region), the capability hs should be given. Special strings that go to a given 
column of the status line and return from the status line can be given as tsl and 
fsl. (fsl must leave the cursor position in the same place it was before tsl. If 
necessary, the sc and rc strings can be included in tsl and fsl to get this effect.) 
The capability tsl takes one parameter, which is the column number of the 
status line the cursor is to be moved to. 

If escape sequences and other special commands, such as tab, work while in the 
status line, the flag eslok can be given. A string which turns off the status line 
(or otherwise erases its contents) should be given as dsl. If the terminal has 
commands to save and restore the position of the cursor, give them as sc and rc. 
The status line is normally assumed to be the same width as the rest of the 
screen, e.g., cols. If the status line is a different width (possibly because the ter- 
minal does not allow an entire line to be loaded) the width, in columns, can be 
indicated with the numeric parameter wsl. 
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Line Graphics 

If the terminal has a line drawing alternate character set, the mapping of glyph 
to character would be given in acsc. The definition of this string is based on the 
alternate character set used in the DEC VT100 terminal, extended slightly with 
some characters from the AT&T 4410vl terminal. 



glyph name vtl00+ 

character 

arrow pointing right + 

arrow pointing left , 

arrow pointing down 
solid square block 0 

lantern symbol I 

arrow pointing up — 

diamond ' 

checker board (stipple) a 

degree symbol f 

plus/minus g 

board of squares h 

lower right corner j 

upper right corner k 

upper left corner 1 

lower left corner m 

plus n 

scan line 1 o 

horizontal line q 

scan line 9 s 

left tee (|-) t 

right tee (— |) u 

bottom tee (1) v 

top tee (J) w 

vertical line x 

bullet 



The best way to describe a new terminal's line graphics set is to add a third 
column to the above table with the characters for the new terminal that produce 
the appropriate glyph when the terminal is in the alternate character set mode. 
For example. 
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glyph name 


vtl00+ 


new tty 


char 


char 


upper left corner 


1 


R 


lower left corner 


m 


F 


upper right corner 


k 


T 


lower right corner 


j 


G 


horizontal line 


q 


/ 


vertical line 


X 





Now write down the characters left to right, as in "acsc=lRmFkTjGq\,x.". 
Miscellaneous 

If the terminal requires other than a null (zero) character as a pad, then this can 
be given as pad. Only the first character of the pad string is used. If the ter- 
minal does not have a pad character, specify npc. 

If the terminal can move up or down half a line, this can be indicated with hu 
(half-line up) and hd (half-line down). This is primarily useful for superscripts 
and subscripts on hardcopy terminals. If a hardcopy terminal can eject to the 
next page (form feed), give this as ff (usually control L). 

If there is a command to repeat a given character a given number of times (to 
save time transmitting a large number of identical characters) this can be indi- 
cated with the parameterized string rep. The first parameter is the character to 
be repeated and the second is the number of times to repeat it. Thus, 
tparm(repeat_char, 'x', 10) is the same as xxxxxxxxxx. 

If the terminal has a settable command character, such as the Tektronix 4025, 
this can be indicated with cmdch. A prototype command character is chosen 
which is used in all capabilities. This character is given in the cmdch capability 
to identify it. The following convention is supported on some UNIX systems: If 
the environment variable CC exists, all occurrences of the prototype character 
are replaced with the character in CC. 

Terminal descriptions that do not represent a specific kind of known terminal, 
such as switch, dialup, patch, and network, should include the gn (generic) 
capability so that programs can complain that they do not know how to talk to 
the terminal. (This capability does not apply to virtual terminal descriptions for 
which the escape sequences are known.) If the terminal is one of those sup- 
ported by the UNIX system virtual terminal protocol, the terminal number can be 
given as vt. A line-turn-around sequence to be transmitted before doing reads 
should be specified in rfi. 

If the terminal uses xon/xoff handshaking for flow control, give xon. Padding 
information should still be included so that routines can make better decisions 
about costs, but actual pad characters will not be transmitted. Sequences to turn 
on and off xon/xoff handshaking may be given in smxon and rmxon. If the 
characters used for handshaking are not *S and *Q, they may be specified with 
xonc and xoffc. 

If the terminal has a "meta key" which acts as a shift key, setting the 8th bit of 
any character transmitted, this fact can be indicated with km. Otherwise, 
software will assume that the 8th bit is parity and it will usually be cleared. If 
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strings exist to turn this "meta mode" on and off, they can be given as smm and 

rmm. 

If the terminal has more lines of memory than will fit on the screen at once, the 
number of lines of memory can be indicated with lm. A value of lm#0 indi- 
cates that the number of lines is not fixed, but that there is still more memory 
than fits on the screen. 

Media copy strings which control an auxiliary printer connected to the terminal 
can be given as mcO: print the contents of the screen, mc4: turn off the printer, 
and mc5: turn on the printer. When the printer is on, all text sent to the ter- 
minal will be sent to the printer. A variation, mc5p, takes one parameter, and 
leaves printer on for as many characters as the value of the parameter, then 
turns the printer off. The parameter should not exceed 255. If the text is not 
displayed on the terminal screen when the printer is on, specify mc5i (silent 
printer). All text, including mc4, is transparently passed to the printer while an 
mc5p is in effect. 

Special Cases 

The working model used by terminfo fits most terminals reasonably well. How- 
ever, some terminals do not completely match that model, requiring special sup- 
port by terminfo. These are not meant to be construed as deficiencies in the ter- 
minals; they are just differences between the working model and the actual 
hardware. They may be unusual devices or, for some reason, do not have all 
the features of the terminfo model implemented. 

Terminals which can not display tilde (~) characters, such as certain Hazeltine 
terminals, should indicate hz. 

Terminals which ignore a linefeed immediately after an am wrap, such as the 
Concept 100, should indicate xenl. Those terminals whose cursor remains on 
the right-most column until another character has been received, rather than 
wrapping immediately upon receiving the right-most character, such as the 
VT100, should also indicate xenl. 

If el is required to get rid of standout (instead of writing normal text on top of 
it), xhp should be given. 

Those Teleray terminals whose tabs turn all characters moved over to blanks, 
should indicate xt (destructive tabs). This capability is also taken to mean that it 
is not possible to position the cursor on top of a "magic cookie" therefore, to 
erase standout mode, it is instead necessary to use delete and insert line. 

Those Beehive Superbee terminals which do not transmit the escape or con- 
trol— C characters, should specify xsb, indicating that the fl key is to be used for 
escape and the f2 key for control-C. 

Similar Terminals 

If there are two very similar terminals, one can be defined as being just like the 
other with certain exceptions. The string capability use can be given with the 
name of the similar terminal. The capabilities given before use override those in 
the terminal type invoked by use. A capability can be canceled by placing rt@ 
to the left of the capability definition, where xx is the capability. For example, 
the entry 
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att4424-2 ! Teletype 4424 in display function 
group ii, 

rev@, sgr@, smul@, use=att4424, 

defines an AT&T 4424 terminal that does not have the rev, sgr, and smul capa- 
bilities, and hence cannot do highlighting. This is useful for different modes for 
a terminal, or for different user preferences. More than one use capability may 
be given. 

FILES 

/usr/lib/terminfo/?/* compiled terminal description database 
/usr/lib/. CORE term/?/* subset of compiled terminal description database 

/usr/lib/tabset/* tab settings for some terminals, in a format 

appropriate to be output to the terminal (escape 
sequences that set margins and tabs) 

SEE ALSO 

curses(3X), printf(3S), term(5). 

captoinfo(lM), infocmp(lM), tic(lM), tty(7) in the System Administrator's Refer- 
ence Manual . 

tput(l) in the User's Reference Manual. 

Chapter 10 of the Programmer's Guide. 

WARNING 

As described in the "Tabs and Initialization" section above, a terminal's initializa- 
tion strings, isl, is2, and is3, if defined, must be output before a curses( 3X) pro- 
gram is run. An available mechanism for outputting such strings is tput init 
(see tput( 1) and profile (4)). 

Tampering with entries in /usr /lib / .COREterm/? /* or /usr/lib/terminfo/?/* (for 
example, changing or removing an entry) can affect programs such as vi( 1) that 
expect the entry to be present and correct. In particular, removing the descrip- 
tion for the "dumb" terminal will cause unexpected problems. 

NOTE 

The termcap database (from earlier releases of UNIX System V) may not be sup- 
plied in future releases. 
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NAME 

timezone — set default system time zone 

SYNOPSIS 

/etc/TIMEZONE 

DESCRIPTION 

This file sets and exports the time zone environmental variable TZ. 
This file is "dotted” into other files that must know the time zone. 
EXAMPLES 

/etc/TIMEZONE for the east coast: 

# Time Zone 
TZ=EST5EDT 
export TZ 



SEE ALSO 

ctime(3C), profile(4). 

rc2(lM) in the System Administrator's Reference Manual. 



605 




UNISTD(4) 



UNISTD(4) 



NAME 

unistd — file header for symbolic constants 
SYNOPSIS 

#include <unistd.h> 

DESCRIPTION 

The header file <unistd.h> lists the symbolic constants and structures not 
already defined or declared in some other header file. 

/* Symbolic constants for the "access" routine: */ 



#define R_OK 
#define W_OK 
#define X_OK 
#define F_OK 

#define F_ULOCK 
#define F LOCK 
#define F TLOCK 
#define FTEST 

/♦Symbolic constants 

#define SEEKSET 
#define SEEK_CUR 
# define SEEK END 



/♦Pathnames:*/ 

#define GF PATH 
#define PF PATH 



4 /*Test for Read permission */ 

2 /*Test for Write permission */ 

1 /*Test for eXecute permission */ 

0 /*Test for existence of File */ 

0 /*Unlock a previously locked region */ 

1 /*Lock a region for exclusive use */ 

2 /*Test and lock a region for exclusive use */ 

3 /*Test a region for other processes locks */ 

for the "lseek" routine: */ 

0 /* Set file pointer to "offset" * / 

1 /* Set file pointer to current plus "offset" */ 

2 /* Set file pointer to EOF plus "offset" * / 



/etc/group /*Pathname of the group file */ 
/etc/passwd/*Pathname of the passwd file */ 
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NAME 

utmp, wtmp — utmp and wtmp entry formats 
SYNOPSIS 

#include <sys/types.h> 

#include <utmp.h> 

DESCRIPTION 

These files, which hold user and accounting information for such commands as 
who( 1), write( 1), and login( 1), have the following structure as defined by 

<utmp.h>: 

#define UTMPFILE "/etc /utmp" 

#define WTMPFILE "/etc/ wtmp” 



# define ut_name ut_user 




struct utmp { 
char 


ut user[8]; 


/* User login name */ 


char 


ut_id[4]; 


/* /etc/inittab id (usually line #) */ 


char 


ut_line[12]; 


/* device name (console, lnxx) */ 


short 


ut_pid; 


/* process id */ 


short 


utjype; 


/* type of entry */ 


struct 


exit_status { 




short 


e_termination; 


/* Process termination status */ 


short 


e_exit; 


/* Process exit status */ 


} ut_exit; 




/* The exit status of a process 


time_t 


ut_time; 


* marked as DEAD PROCESS. */ 
/* time entry was made */ 



/* Definitions for ut type */ 

#define EMPTY 0 

#define RUNLVL 1 

#define BOOT TIME 2 

#define OLD TIME 3 

#define NEW_TIME 4 

#define INIT_PROCESS 5 

#define LOGIN_PROCESS 6 

#define USER_PROCESS 7 

#define DEAD_PROCESS 8 

#define ACCOUNTING 9 

#define UTMAXTYPE ACCOUNTING 



/* Process spawned by "init" */ 

/* A "getty" process waiting for login */ 
/* A user process * / 

/* Largest legal value of ut_type */ 
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/* Special strings or formats used in the "utline" field when */ 
/* accounting for something other than a process */ 

/* No string for the utjine field can be more than 11 chars + */ 
/* a NULL in length * / 

#define RUNLVL MSG "run-level %c" 

#define BOOT MSG "system boot" 

#define OTIME MSG "old time" 

#define NTIME MSG "new time" 

FILES 

/etc/utmp 

/etc/wtmp 

SEE ALSO 

getut(3C). 

login(l), who(l), write(l) in the User's Reference Manual. 
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NAME 

intro — introduction to miscellany 
DESCRIPTION 

This section describes miscellaneous facilities such as macro packages, character 
set tables, etc. 
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NAME 

ascii — map of ASCII character set 
DESCRIPTION 

ascii is a map of the ASCII character set, giving both octal and hexadecimal 
equivalents of each character, to be printed as needed. It contains: 



|000 


nul 


|001 


soh 


1 002 


stx 


1 003 


etx 


1 004 


eot 


1 005 


enq 


1 006 


ack 


1 007 


bel | 


|010 


bs 


|011 


ht 


1 012 


nl 


j 013 


vt 


j 014 


np 


1 015 


cr 


1 0 1 6 


so 


1 0 1 7 


si | 


1 020 


die 


1 021 


del 


1 022 


dc2 


1 023 


dc3 


024 


dc4 


025 


nak 


j 026 


syn 


j 027 


etb j 


j 030 


can 


1 031 


em 


1 032 


sub 


033 


esc 


034 


fs 


1 035 


gs 


1 036 


rs 


j 037 


us | 


j 040 


sp 


1 041 


j 


042 


t! 


043 


# 


j 044 


$ 


j 045 


% 


j 046 


& 


j 047 




j 050 


( 


1 051 


) 


1 052 


* 


j 053 


+ 


j 054 


, 


j 055 


- 


1 056 


. 


j 057 


/ 1 


j 060 


0 


1 061 


1 


|062 


2 


|063 


3 


j 064 


4 


j 065 


5 


j 066 


6 


j 067 


7 I 


j 070 


8 


j 071 


9 


j 072 




j 073 


; 


j 074 


< 


j 075 


= 


j 076 


> 


1 077 


? j 


j 100 


@ 


1 101 


A 


j 102 


B 


j 103 


c 


1 104 


D 


1 105 


E 


1 106 


F 


j 107 


G | 


j 110 


H 


j 111 


I 


1 112 


J 


1 113 


K 


114 


L 


115 


M 


1 116 


N 


1 117 


O | 


j 120 


P 


1 121 


Q 


j 122 


R 


123 


S 


j 124 


T 


1 125 


U 


j 126 


V 


1 127 


W j 


130 


X 


1 131 


Y 


132 


Z 


j 133 


[ 


j 134 


\ 


1 135 


i 


1 136 


a 


j 137 




1 140 


/ 


j 141 


a 


j 142 


b 


j 143 


c 


j 144 


d 


1 145 


e 


1 146 


f 


1 147 


g 1 


j 150 


h 


j 151 


i 


j 152 


i 


1 153 


k 


1 154 


1 


j 155 


m 


1 156 


n 


1 157 


o | 


j 160 


P 


j 161 


q 


162 


r 


j 163 


s 


j 164 


t 


1 165 


u 


1 166 


V 


1 167 


w | 


j 170 


X 


1 171 


y 


172 


z 


j 173 


{ 


j 174 


1 


j 175 


) 


j 176 




1 177 


del j 


| 00 


nul 


1 oi 


soh 


| 02 


stx 


| 03 


etx 


| 04 


eot 


| 05 


enq 


| 06 


ack 


| 07 


bel | 


j 08 


bs 


| 09 


ht 


| 0a 


nl 


j 0b 


vt 


| 0c 


np 


| Od 


cr 


j Oe 


so 


1 Of 


s i | 


| 10 


die 


1 11 


del 


1 12 


dc2 


1 13 


dc3 


1 14 


dc4 


j 15 


nak 


j 16 


syn 


j 17 


etb j 


1 18 


can 


1 19 


em 


1 la 


sub 


1 lb 


esc 


1 1c 


f s 


1 lb 


g s 


1 le 


rs 


1 If 


us | 


| 20 


sp 


1 21 


i 


| 22 


" 


| 23 


# 


1 24 


$ 


1 25 


% 


1 26 


& 


j 27 




| 28 


( 


| 29 


) 


1 2a 


* 


j 2b 


+ 


j 2c 


, 


j 2d 


- 


2e 




2f 


/ 1 


j 30 


0 


1 31 


1 


| 32 


2 


| 33 


3 


1 34 


4 


| 35 


5 


| 36 


6 


| 37 


7 I 


| 38 


8 


| 39 


9 


| 3a 




| 3b 


; 


1 3c 


< 


| 3d 


= 


1 3e 


> 


1 3f 


? j 


| 40 


@ 


1 41 


A 


1 42 


B 


1 43 


c 


j 44 


D 


1 45 


E 


| 46 


F 


| 47 


G | 


j 48 


H 


j 49 


I 


| 4a 


J 


| 4b 


K 


j 4c 


L 


| 4d 


M 


j 4e 


N 


j 4f 


O | 


j 50 


P 


1 51 


Q 


1 52 


R 


| 53 


S 


54 


T 


j 55 


U 


56 


V 


1 57 


W j 


j 58 


X 


1 59 


Y 


| 5a 


Z 


j 5b 


[ 


j 5c 


\ 


| 5d 


] 


1 5e 


A 


| 5f 




| 60 




1 61 


a 


1 62 


b 


| 63 


c 


| 64 


d 


| 65 


e 


j 66 


f 


1 67 


g 1 


j 68 


h 


69 


i 


| 6a 


i 


| 6b 


k 


1 6c 


1 


| 6d 


m 


j 6e 


n 


j 6f 


o | 


1 70 


P 


1 71 


q 


| 72 


r 


| 73 


s 


| 74 


t 


1 75 


u 


1 76 


V 


77 


w I 


j 78 


X 


| 79 


y 


1 7a 


z 


1 7b 


{ 


1 7c 


1 


1 7d 


} 


1 7e 




| 7f 


del j 
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NAME 

environ — user environment 
DESCRIPTION 

An array of strings called the "environment" is made available by exec (2) when 
a process begins. By convention, these strings have the form "name=value". 
The following names are used by various commands: 

PATH The sequence of directory prefixes that sh( 1), time( 1), nice( 1), nohup( 1), 
etc., apply in searching for a file known by an incomplete path name. 
The prefixes are separated by colons (:). Login( 1) sets 

PATH=: /bin: /usr /bin. 

HOME Name of the user's login directory, set by login( 1) from the password file 
passwd( 4). 

TERM The kind of terminal for which output is to be prepared. This informa- 
tion is used by commands, such as mm( 1) or tplot(lG), which may 
exploit special capabilities of that terminal. 

TZ Time zone information. The format is xxxnzzz where xxx is standard 
local time zone abbreviation, n is the difference in hours from GMT, and 
zzz is the abbreviation for the daylight-saving local time zone, if any; 
for example, EST5EDT. 

Further names may be placed in the environment by the export command and 
"name= value" arguments in sh( 1), or by exec (2). It is unwise to conflict with 
certain shell variables that are frequently exported by .profile files: MAIL, PS1, 
PS2, IFS. 

SEE ALSO 

exec(2). 

env(l), login(l), sh(l), nice(l), nohup(l), time(l), tplot(lG) in the User's Refer- 
ence Manual. 

mm(l) in the DOCUMENTER'S WORKBENCH Software Release 2.0 Technical Dis- 
cussion and Reference Manual. 
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NAME 

fcntl — file control options 
SYNOPSIS 

#include <fcntl.h> 

DESCRIPTION 

The fcntl (2) function provides for control over open files. This include file 
describes requests and arguments to fcntl and open( 2). 

/* Flag values accessible to open(2) and fcntl(2) */ 

/* (The first three can only be set by open) * / 

#define ORDONLY 0 

# define 0_WR0NLY 1 

# define 0_RDWR 2 

#define ONDELAY 04 /* Non-blocking I/O */ 

#define 0_APPEND 010 /* append (writes guaranteed at the end) */ 

#define 0_SYNC 020 /* synchronous write option */ 



/* Flag values accessible only to open(2) */ 

#define 0_CREAT 00400 /* open with file create (uses third open arg)*/ 

#define OJTRUNC 01000 /* open with truncation */ 

#define 0_EXCL 02000 /* exclusive open */ 



/* fcntl(2) requests */ 
#define F DUPFD 0 
# define F GETFD 1 
#define F SETFD 2 
#define F GETFL 3 
#define F SETFL 4 
#define FGETLK 5 
#define F SETLK 6 
# define F SETLKW 7 
# define F CHKFL 8 



/* Duplicate fildes */ 

/* Get fildes flags */ 

/* Set fildes flags */ 

/* Get file flags */ 

/* Set file flags */ 

/* Get file lock */ 

/* Set file lock */ 

/* Set file lock and wait */ 

/* Check legality of file flag changes */ 



/* file segment locking control structure */ 
struct flock { 

short l_type; 
short l whence; 
long l start; 

long l ien; /* if 0 then until EOF */ 

short l_sysid; /* returned with F GETLK*/ 

short l_pid; /* returned with F GETLK*/ 



/* file segment locking types */ 

#define F RDLCK 01 /* Read lock */ 

#define F WRLCK 02 /* Write lock */ 

#define FJJNLCK 03 /* Remove locks */ 

SEE ALSO 

fcntl(2), open(2). 
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NAME 

j agent — host control of windowing terminal 
SYNOPSIS 

#include < sys /jioctl.h > 

ioctl (cntlfd, JAGENT, &arg) 

int cntlfd 
struct bagent arg 

DESCRIPTION 

The ioctl{ 2) system call, when performed on an xt(7) device with the JAGENT 
request, allows a host program to send information to a windowing terminal. 

ioctl has three arguments: 

cntlfd the xt(7) control channel file descriptor 

JAGENT the xt(7) ioctl(2) request to invoke a windowing terminal agent rou- 
tine. 

arg the address of a bagent structure, defined in <sys/jioctl.h> as fol- 

lows: 

struct 
int 
char 
char 

} ; 

The src pointer must be initialized to point to a byte string which is 
sent to the windowing terminal. See layers(5) for a list of JAGENT 
strings recognized by windowing terminals. Likewise, the dest 
pointer must be initialized to the address of a buffer to receive a byte 
string returned by the terminal. When ioctl( 2) is called, the size argu- 
ment must be set to the length of the src string. Upon return, size is 
set by ioctl( 2) to the length of the destination byte string, dest. 

RETURN VALUE 

Upon successful completion, the size of the destination byte string is returned. 
If an error occurs, —1 is returned. 

SEE ALSO 

ioctl(2), layers(5), libwindows(3X). 

xt(7) in the System Administrator's Reference Manual. 



bagent { 

size; /* size of src in & dest out */ 
*src; /* the source byte string */ 
*dest; /* the destination byte string */ 
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NAME 

layers — protocol used between host and windowing terminal under layers^ 1) 
SYNOPSIS 

#include <sys/jioctl.h> 

DESCRIPTION 

layers are asynchronous windows supported by the operating system in a win- 
dowing terminal. Communication between the UNIX system processes and ter- 
minal processes under layers^ 1) occurs via multiplexed channels managed by the 
respective operating systems using a protocol as specified in xtproto(5). 

The contents of packets transferring data between a UNIX system process and a 
layer are asymmetric. Data sent from the UNIX system to a particular terminal 
process is undifferentiated and it is up to the terminal process to interpret the 
contents of packets. 

Control information for terminal processes is sent via channel 0. Process 0 in 
the windowing terminal performs the designated functions on behalf of the pro- 
cess connected to the designated channel. These packets take the form: 

command, channel 

except for timeout and jagent information which take the form 

command, data. . . 

The commands are the bottom eight bits extracted from the following ioctl(2) 
codes: 

JBOOT Prepare to load a new terminal program into the designated layer. 

JTERM Kill the downloaded layer program, and restore the default window 
program. 

JTIMO Set the timeout parameters for the protocol. The data consist of two 
bytes: the value of the receive timeout in seconds, and the value of 
the transmit timeout in seconds. 

JTIMOM Set the timeout parameters for the protocol. The data consist of four 
bytes in two groups: the value of the receive timeout in milliseconds 
(the low eight bits followed by the high eight bits) and the value of 
the transmit timeout (in the same format). 

JZOMBOOT 

Like JBOOT, but do not execute the program after loading. 

JAGENT Send a source byte string to the terminal agent routine and wait for a 
reply byte string to be returned. 

The data are from a bagent structure (see jagent(5)) and consist of a 
one-byte size field followed by a two-byte agent command code and 
parameters. Two-byte integers transmitted as part of an agent com- 
mand are sent with the high-order byte first. The response from the 
terminal is generally identical to the command packet, with the two 
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command bytes replaced by the return code: 0 for success, — 1 for 
failure. Note that the routines in the libwindow$( 3X) library all send 
parameters in an agentrect structure. The agent command codes and 
their parameters are as follows: 



ANEWLAYER 

A CURRENT 

ADELETE 

ATOP 

ABOTTOM 

AMOVE 

ARE SHAPE 

A_NEW 

AEXIT 



followed by a two-byte channel number and a rec- 
tangle structure (four two-byte coordinates). 

followed by a two-byte channel number, 
followed by a two-byte channel number, 
followed by a two-byte channel number, 
followed by a two-byte channel number. 

followed by a two-byte channel number and a 
point to move to (two two-byte coordinates). 

followed by a two-byte channel number and the 
new rectangle (four two-byte coordinates). 

followed by a two-byte channel number and a rec- 
tangle structure (four two-byte coordinates). 

no parameters needed. 



A ROMVERSION no parameters needed. The response packet con- 
tains the size byte, two-byte return code, two 
unused bytes, and the parameter part of the ter- 
minal id string (e.g., "8; 7; 3”). 



Packets from the windowing terminal to the UNIX system all take the following 
form: 



command, data. . . 



The single-byte commands are as follows: 

C SENDCHAR Send the next byte to the UNIX system process. 

C NEW Create a new UNIX system process group for this layer. 

Remember the window size parameters for this layer. 
The data for this command is in the form described by 
the jw insize structure. The size of the window is 
specified by two 2-byte integers, sent low byte first. 

C UNBLK Unblock transmission to this layer. There is no data for 

this command. 



C DELETE Delete the UNIX system process group attached to this 

layer. There is no data for this command. 

C EXIT Exit. Kill all UNIX system process groups associated with 

this terminal and terminate the session. There is no 
data for this command. 
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CJDEFUNCT Layer program has died, send a terminate signal to the 

UNIX system process groups associated with this ter- 
minal. There is no data for this command. 

C SENDNCHARS The rest of the data are characters to be passed to the 
UNIX system process. 

C RESHAPE The layer has been reshaped. Change the window size 

parameters for this layer. The data takes the same form 
as for the C NEW command. 

SEE ALSO 

libwindows(3X), jagent(5), xtproto(5). 

layers(l) in the User's Reference Manual. 

xt(7) in the System Administrator's Reference Manual. 
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NAME 

math — math functions and constants 
SYNOPSIS 

#include <math.h> 

DESCRIPTION 

This file contains declarations of all the functions in the Math Library (described 
in Section 3M), as well as various functions in the C Library (Section 3C) that 
return floating-point values. 

It defines the structure and constants used by the matherr{ 3M) error-handling 
mechanisms, including the following constant used as an error-return value: 

HUGE The maximum value of a single-precision floating-point 

number. 

The following mathematical constants are defined for user convenience: 

M E The base of natural logarithms (e). 

MLOG2E The base-2 logarithm of e. 

M LOGIOE The base- 10 logarithm of e. 

M LN2 The natural logarithm of 2. 

MJLN10 The natural logarithm of 10. 

M_PI it, the ratio of the circumference of a circle to its diameter. 

M_PI_2 ir/2. 

M_PI_4 tt/4. 

M l PI 1 /tt. 

M_2_PI 2/tt. 

M_2_SQRTPI 2/tt. 

M SQRT2 The positive square root of 2. 

M SQRT12 The positive square root of 1/2. 

For the definitions of various machine-dependent "constants," see the descrip- 
tion of the <values.h> header file. 

SEE ALSO 

intro(3), matherr(3M), values(5). 
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NAME 

prof — profile within a function 

SYNOPSIS 

#define MARK 
#include <prof.h> 

void MARK (name) 

DESCRIPTION 

MARK will introduce a mark called name that will be treated the same as a func- 
tion entry point. Execution of the mark will add to a counter for that mark, and 
program-counter time spent will be accounted to the immediately preceding 
mark or to the function if there are no preceding marks within the active func- 
tion. 

Name may be any combination of numbers or underscores. Each name in a 
single compilation must be unique, but may be the same as any ordinary pro- 
gram symbol. 

For marks to be effective, the symbol MARK must be defined before the header 
file <prof.h> is included. This may be defined by a preprocessor directive as in 
the synopsis, or by a command line argument, i.e: 

cc — p — DMARK foo.c 

If MARK is not defined, the MARK (name) statements may be left in the source 
files containing them and will be ignored. 

EXAMPLE 

In this example, marks can be used to determine how much time is spent in 
each loop. Unless this example is compiled with MARK defined on the command 
line, the marks are ignored. 

#include <prof.h> 



int i, j; 



MARK(loopl); 

for (i — 0; i < 2000; i++) { 

} 

MARK(loop2); 

for (j = 0; j < 2000; j++) { 

} 



prof(l), profil(2), monitor(3C). 




} 

SEE ALSO 
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NAME 

regexp — regular expression compile and match routines 
SYNOPSIS 

# define INIT < declarations > 

#define GETCO <getc code> 

#define PEEKCO <peekc code> 

#define UNGETC(c) Cungetc code> 

#define RETURN(pointer) < return code> 

#define ERROR(val) < error code> 

#include <regexp.h> 

char * compile (instring, expbuf, endbuf, eof) 
char *instring, *expbuf, *endbuf; 
int eof; 

int step (string, expbuf) 
char *string, *expbuf; 

extern char *locl, *loc2, *locs; 
extern int circf, sed, nbra; 

DESCRIPTION 

This page describes general-purpose regular expression matching routines in the 
form of ed( 1), defined in <regexp.h> . Programs such as ed( 1), sed( 1), grep( 1), 
bs(l), expr( 1), etc., which perform regular expression matching use this source 
file. In this way, only this file need be changed to maintain regular expression 
compatibility. 

The interface to this file is unpleasantly complex. Programs that include this file 
must have the following five macros declared before the 
"#include <regexp.h>" statement. These macros are used by the compile rou- 
tine. 



GETC() 

PEEKC() 



UNGETC(c) 



RETURN (pointer) 



Return the value of the next character in the regular 
expression pattern. Successive calls to GETC() should 
return successive characters of the regular expression. 

Return the next character in the regular expression. Suc- 
cessive calls to PEEKC() should return the same character 
[which should also be the next character returned by 
GETC()]. 

Cause the argument c to be returned by the next call to 
GETC() [and PEEKC()]. No more that one character of 
pushback is ever needed and this character is guaranteed 
to be the last character read by GETCQ. The value of the 
macro UNGETC(c) is always ignored. 

This macro is used on normal exit of the compile routine. 
The value of the argument pointer is a pointer to the char- 
acter after the last character of the compiled regular 
expression. This is useful to programs which have 
memory allocation to manage. 
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ERROR (val) This is the abnormal return from the compile routine. The 

argument val is an error number (see table below for 



ERROR 


meanings). This call should never return. 
MEANING 


11 


Range endpoint too large. 


16 


Bad number. 


25 


"\digit" out of range. 


36 


Illegal or missing delimiter. 


41 


No remembered search string. 


42 


\( \) imbalance. 


43 


Too many \(. 


44 


More than 2 numbers given in \{ \). 


45 


} expected after \. 


46 


First number exceeds second in \{ \}. 


49 


[ ] imbalance. 


50 


Regular expression overflow. 



The syntax of the compile routine is as follows: 
compile(instring, expbuf, endbuf, eof) 

The first parameter instring is never used explicitly by the compile routine but is 
useful for programs that pass down different pointers to input characters. It is 
sometimes used in the INIT declaration (see below). Programs which call func- 
tions to input characters or have characters in an external array can pass down a 
value of ((char *) 0) for this parameter. 

The next parameter expbuf is a character pointer. It points to the place where 
the compiled regular expression will be placed. 

The parameter endbuf is one more than the highest address where the compiled 
regular expression may be placed. If the compiled expression cannot fit in 
(endbuf— expbuf) bytes, a call to ERROR(50) is made. 

The parameter eof is the character which marks the end of the regular expres- 
sion. For example, in ed( 1), this character is usually a /. 

Each program that includes this file must have a #define statement for INIT. 
This definition will be placed right after the declaration for the function compile 
and the opening curly brace ({). It is used for dependent declarations and initial- 
izations. Most often it is used to set a register variable to point the beginning of 
the regular expression so that this register variable can be used in the declara- 
tions for GETC(), PEEKCQ and UNGETCQ. Otherwise it can be used to declare 
external variables that might be used by GETCQ, PEEKC() and UNGETCQ. See 
the example below of the declarations taken from grep( 1). 

There are other functions in this file which perform actual regular expression 
matching, one of which is the function step. The call to step is as follows: 

step(string, expbuf) 

The first parameter to step is a pointer to a string of characters to be checked for 
a match. This string should be null terminated. 
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The second parameter expbuf is the compiled regular expression which was 
obtained by a call of the function compile . 

The function step returns non-zero if the given string matches the regular 
expression, and zero if the expressions do not match. If there is a match, two 
external character pointers are set as a side effect to the call to step. The vari- 
able set in step is loci. This is a pointer to the first character that matched the 
regular expression. The variable loc2, which is set by the function advance, 
points to the character after the last character that matches the regular expres- 
sion. Thus if the regular expression matches the entire line, loci will point to 
the first character of string and loc2 will point to the null at the end of string. 

Step uses the external variable circf which is set by compile if the regular expres- 
sion begins with If this is set then step will try to match the regular expres- 
sion to the beginning of the string only. If more than one regular expression is 
to be compiled before the first is executed the value of circf should be saved for 
each compiled expression and circf should be set to that saved value before each 
call to step. 

The function advance is called from step with the same arguments as step. The 
purpose of step is to step through the string argument and call advance until 
advance returns non-zero indicating a match or until the end of string is reached. 
If one wants to constrain string to the beginning of the line in all cases, step 
need not be called; simply call advance. 

When advance encounters a * or \{ \} sequence in the regular expression, it will 
advance its pointer to the string to be matched as far as possible and will recur- 
sively call itself trying to match the rest of the string to the rest of the regular 
expression. As long as there is no match, advance will back up along the string 
until it finds a match or reaches the point in the string that initially matched the 
* or \{ \}. It is sometimes desirable to stop this backing up before the initial 
point in the string is reached. If the external character pointer Iocs is equal to 
the point in the string at sometime during the backing up process, advance will 
break out of the loop that backs up and will return zero. This is used by ed( 1) 
and sed(l) for substitutions done globally (not just the first occurrence, but the 
whole line) so, for example, expressions like s/y*//g do not loop forever. 

The additional external variables sed and nbra are used for special purposes. 



EXAMPLES 

The following is an example of how the regular expression macros and calls look 
from grep( 1): 



#define INIT 
# define GETCQ 
# define PEEKCQ 
#define UNGETC(c) 
#define RETURN(c) 
#define ERROR(c) 



register char *sp = instring; 
(*sp++) 

(*sp) 

( — sp) 
return; 
regerrQ 
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#include <regexp.h> 

(void) compile(*argv, expbuf, &expbuf[ESIZE], \0'); 

if (step(linebuf, expbuf)) 

succeed(); 



SEE ALSO 

ed(l), expr(l), grep(l), sed(l) in the User's Reference Manual. 
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NAME 

stat — data returned by stat system call 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/stat.h> 

DESCRIPTION 

The system calls stat and fstat return data whose structure is defined by this 
include file. The encoding of the field stjnode is defined in this file also. 

Structure of the result of stat 

struct stat 

{ 

dev_t st_dev; 
ushort st_ino; 
ushort stjnode; 
short stjilink; 

ushort stjiid; 
ushort st_gid; 
dev_t stjrdev; 
off_t stsize; 

timet statime; 
time_t stjntime; 
time_t st_ctime; 

}; 

#define S IFMT 0170000 /* type of file */ 

#define SJFDIR 0040000 /* directory */ 

#define SJFCHR 0020000 /* character special */ 

#define S IFBLK 0060000 /* block special */ 

#define S IFREG 0100000 /* regular •/ 

#define SJFIFO 0010000 /? fifo */ 

#define S ISUID 04000 /* set user id on execution */ 

#define S_ISGID 02000 /* set group id on execution */ 

#define SJSVTX 01000 /* save swapped text even after use */ 

#define S IREAD 00400 /* read permission, owner */ 

#define SJWRITE 00200 /* write permission, owner */ 

#define SJEXEC 00100 /* execute/search permission, owner */ 

#define S ENFMT S_ISGID /* record locking enforcement flag */ 

#define S IRWXU 00700 /* read, write, execute: owner */ 

#define S IRUSR 00400 /* read permission: owner */ 

#define S IWUSR 00200 /* write permission: owner */ 

#define S IXUSR 00100 /* execute permission: owner */ 

#define S IRWXG 00070 /* read, write, execute: group */ 

#define SJRGRP 00040 /* read permission: group */ 

#define SJWGRP 00020 /* write permission: group */ 

#define S IXGRP 00010 /* execute permission: group */ 

#define S IRWXO 00007 /* read, write, execute: other */ 

#define S IROTH 00004 /* read permission: other */ 
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#define SJWOTH 00002 /* write permission: other * / 

#define SJXOTH 00001 /* execute permission: other */ 

SEE ALSO 

stat(2), types(5). 
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NAME 

term — conventional names for terminals 
DESCRIPTION 

These names are used by certain commands (e.g., man( 1), tabs( 1), tput(l), vi( 1) 
and curses (3X)) and are maintained as part of the shell environment in the 
environment variable TERM (see sh( 1), profile (4), and environ(5)). 

Entries in terminfo( 4) source files consist of a number of comma-separated fields. 
(To obtain the source description for a terminal, use the —I option of 
infocmp (1M).) White space after each comma is ignored. The first line of each 
terminal description in the terminfo(4) database gives the names by which ter - 
minfo( 4) knows the terminal, separated by bar ( | ) characters. The first name 
given is the most common abbreviation for the terminal (this is the one to use to 
set the environment variable TERMINFO in $HOME / .profile ; see profile( 4)), the 
last name given should be a long name fully identifying the terminal, and all 
others are understood as synonyms for the terminal name. All names but the 
last should contain no blanks and must be unique in the first 14 characters; the 
last name may contain blanks for readability. 

Terminal names (except for the last, verbose entry) should be chosen using the 
following conventions. The particular piece of hardware making up the terminal 
should have a root name chosen, for example, for the AT&T 4425 terminal, 
att4425. This name should not contain hyphens, except that synonyms may be 
chosen that do not conflict with other names. Up to 8 characters, chosen from 
[a— zO— 9], make up a basic terminal name. Names should generally be based on 
original vendors, rather than local distributors. A terminal acquired from one 
vendor should not have more than one distinct basic name. Terminal sub- 
models, operational modes that the hardware can be in, or user preferences, 
should be indicated by appending a hyphen and an indicator of the mode. 
Thus, an AT&T 4425 terminal in 132 column mode would be att4425— w. The 
following suffixes should be used where possible: 



Suffix 


Meaning 


Example 


— w 


Wide mode (more than 80 columns) 


att4425— w 


—am 


With auto, margins (usually default) 


vtlOO— am 


— nam 


Without automatic margins 


vtlOO— nam 


— n 


Number of lines on the screen 


aaa— 60 


-na 


No arrow keys (leave them in local) 


cl 00— na 


-np 


Number of pages of memory 


clOO— 4p 


— rv 


Reverse video 


att4415— rv 



To avoid conflicts with the naming conventions used in describing the different 
modes of a terminal (e.g., — w), it is recommended that a terminal's root name 
not contain hyphens. Further, it is good practice to make all terminal names 
used in the terminfo{ 4) database unique. Terminal entries that are present only 
for inclusion in other entries via the use= facilities should have a '+' in their 
name, as in 4415+nl. 

Some of the known terminal names may include the following (for a complete 
list, type: Is -C /usr/lib/terminfo/?): 
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2621,hp2621 

2631 

2631— c 

2631— e 

2640,hp2640 

2645,hp2645 

3270 

33,tty33 

35,tty35 

3 7, tty 3 7 

4000a 

4014,tek4014 

40,tty40 

43,tty43 

4410,5410 

44 1 0— nfk,54 1 0— nfk 

44 1 0— nsl,54 1 0— nsl 

4410— w,5410— w 

4410vl,5410vl 

44 1 Ovl — w,54 1 Ovl — w 

4415,5420 

4415— nl,5420— nl 

4415— rv,5420— rv 

4415— rv— nl,5420— rv— nl 

4415— w,5420— w 

4415— w—nl,5 420— w—nl 



4415-w-rv,5420-w-rv 
4415— w— rv— nl,5420— w— rv— nl 

4418,5418 
4418— w,5418— w 
4420 
4424 

4424- 2 
4425,5425 

4425— fk,5425— fk 
4425— nl,5425— nl 

4425— w,5425— w 
4425— w— fk,5425-w-fk 

4425— nl— w,5425— nl— w 

4426 

450 

450-12 

500,att500 

510,510a 



Hewlett-Packard 2621 series 

Hewlett-Packard 2631 line printer 

Hewlett-Packard 2631 line printer - compressed mode 

Hewlett-Packard 2631 line printer - expanded mode 

Hewlett-Packard 2640 series 

Hewlett-Packard 2645 series 

IBM Model 3270 

AT&T Teletype Model 33 KSR 

AT&T Teletype Model 35 KSR 

AT&T Teletype Model 37 KSR 

Trendata 4000a 

TEKTRONIX 4014 

AT&T Teletype Dataspeed 40/2 

AT&T Teletype Model 43 KSR 

AT&T 4410/5410 terminal in 80-column mode - version 2 
AT&T 4410/5410 without function keys - version 1 
AT&T 4410/5410 without pin defined 
AT&T 4410/5410 in 132-column mode 
AT&T 4410/5410 terminal in 80-column mode - version 1 
AT&T 4410/5410 terminal in 132-column mode - version 1 
AT&T 4415/5420 in 80-column mode 
AT&T 4415/5420 without changing labels 
AT&T 4415/5420 80 columns in reverse video 
AT&T 4415/5420 reverse video without changing labels 
AT&T 4415/5420 in 132-column mode 
AT&T 4415/5420 in 132-column mode without changing 
labels 

AT&T 4415/5420 132 columns in reverse video 
AT&T 4415/5420 132 columns reverse video 
without changing labels 
AT&T 5418 in 80 -column mode 
AT&T 5418 in 132-column mode 
AT&T Teletype Model 4420 
AT&T Teletype Model 4424 

AT&T Teletype Model 4424 in display function group ii 
AT&T 4425/5425 

AT&T 4425/5425 without function keys 
AT&T 4425/5425 without changing labels in 80-column 
mode 

AT&T 4425/5425 in 132-column mode 
AT&T 4425/5425 without function keys in 132-column 
mode 

AT&T 4425/5425 without changing labels in 132-column 
mode 

AT&T Teletype Model 4426S 
DASI 450 (same as Diablo 1620) 

DASI 450 in 12-pitch mode 

AT&T-IS 500 terminal 

AT&T 510/510a in 80-column mode 
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513bct,att513 

5320 

5420_2 

5420 2— w 

5620,dmd 

5620-24, dmd-24 

5620— 34,dmd— 34 

610,610bct 

610— w,610bct-w 

7300,pc7300,unix_pc 

735,ti 

745 

dumb 



h P 

!p 

pt505 
pt505— 24 
sync 



AT&T 513 bet terminal 
AT&T 5320 hardcopy terminal 
AT&T 5420 model 2 in 80-column mode 
AT&T 5420 model 2 in 132-column mode 
AT&T 5620 terminal 88 columns 
AT&T Teletype Model DMD 5620 in a 24x80 layer 
AT&T Teletype Model DMD 5620 in a 34x80 layer 
AT&T 610 bet terminal in 80-column mode 
AT&T 610 bet terminal in 132-column mode 
AT&T UNIX PC Model 7300 
Texas Instruments TI735 and TI725 
Texas Instruments TI745 
generic name for terminals that lack reverse 
line-feed and other special escape sequences 
Hewlett-Packard (same as 2645) 
generic name for a line printer 
AT&T Personal Terminal 505 (22 lines) 

AT&T Personal Terminal 505 (24-line mode) 
generic name for synchronous Teletype Model 
4540-compatible terminals 



Commands whose behavior depends on the type of terminal should accept argu- 
ments of the form — T term where term is one of the names given above; if no 
such argument is present, such commands should obtain the terminal type from 
the environment variable TERM, which, in turn, should contain term . 



FILES 

/usr/lib/terminfo/?/* compiled terminal description database 
SEE ALSO 

curses(3X), profile(4), terminfo(4), environ(5), 

man(l), sh(l), stty(l), tabs(l), tput(l), tplot(lG), vi(l) in the User's Reference 
Manual 

infocmp(lM) in the System Administrator's Reference Manual. 

Chapter 10 of the Programmer's Guide. 



NOTES 

Not all programs follow the above naming conventions. 
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NAME 

types — primitive system data types 
SYNOPSIS 

#include <sys/types.h> 

DESCRIPTION 

The data types defined in the include file are used in UNIX system code; some 
data of these types are accessible to user code: 



typedef struct { int r[l]; 


} *physadr; 


typedef long 


daddrt; 


typedef char * 


caddrt; 


typedef unsigned char 


unchar; 


typedef unsigned short 


ushort; 


typedef unsigned int 


uint; 


typedef unsigned long 


ulong; 


typedef ushort 


inot; 


typedef short 


cntt; 


typedef long 


time t; 


typedef int 


label J[10]; 


typedef short 


dev t; 


typedef long 


offj; 


typedef long 


paddrt; 


typedef int 


key_t; 


typedef unsigned char 


use_t; 


typedef short 


sysid_t; 


typedef short 


indext; 


typedef short 


lock_t; 


typedef unsigned int 


size_t; 



The form daddrj is used for disk addresses except in an i-node on disk, see 
fs( 4). Times are encoded in seconds since 00:00:00 GMT, January 1, 1970. The 
major and minor parts of a device code specify kind and unit number of a device 
and are installation-dependent. Offsets are measured in bytes from the begin- 
ning of a file. The labelj variables are used to save the processor state while 
another process is running. 

SEE ALSO 

fs(4). 
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NAME 

values — machine-dependent values 
SYNOPSIS 

#include <values.h> 

DESCRIPTION 

This file contains a set of manifest constants, conditionally defined for particular 
processor architectures. 

The model assumed for integers is binary representation (one's or two's comple- 
ment), where the sign is represented by the value of the high-order bit. 

BITS(fype) The number of bits in a specified type (e.g., int). 

HIBITS The value of a short integer with only the high-order bit 

set (in most implementations, 0x8000). 

HIBITL The value of a long integer with only the high-order bit 

set (in most implementations, 0x80000000). 

HIBITI The value of a regular integer with only the high-order bit 

set (usually the same as HIBITS or HIBITL). 

MAXSHORT The maximum value of a signed short integer (in most 

implementations, 0x7FFF = 32767). 

MAXLONG The maximum value of a signed long integer (in most 

implementations, 0x7FFFFFFF = 2147483647). 

MAXINT The maximum value of a signed regular integer (usually 

the same as MAXSHORT or MAXLONG). 

MAXFLOAT, LN MAXFLOAT The maximum value of a single-precision 

floating-point number, and its natural loga- 
rithm. 

MAXDOUBLE, LN MAXDOUBLE The maximum value of a double-precision 

floating-point number, and its natural loga- 
rithm. 



MINFLOAT, LN MINFLOAT The minimum positive value of a single- 

precision floating-point number, and its natural 
logarithm. 

MINDOUBLE, LN MINDOUBLE The minimum positive value of a double- 

precision floating-point number, and its natural 
logarithm. 

FSIGNIF The number of significant bits in the mantissa of a single- 

precision floating-point number. 

DSIGNIF The number of significant bits in the mantissa of a 

double-precision floating-point number. 



SEE ALSO 

intro(3), math(5). 
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NAME 

varargs — handle variable argument list 
SYNOPSIS 

#include <varargs.h> 

vaalist 

vadcl 

void va_start(pvar) 
valist pvar; 

type vaarg(pvar, type) 
va list pvar; 

void va_end(pvar) 
va list pvar; 

DESCRIPTION 

This set of macros allows portable procedures that accept variable argument lists 
to be written. Routines that have variable argument lists [such as printf( 3S)] but 
do not use varargs are inherently nonportable, as different machines use 
different argument-passing conventions. 

va_alist is used as the parameter list in a function header. 
va_dcl is a declaration for vajdist. No semicolon should follow va_dcL 
va_list is a type defined for the variable used to traverse the list. 
va_start is called to initialize pvar to the beginning of the list. 

va_arg will return the next argument in the list pointed to by pvar. Type is the 
type the argument is expected to be. Different types can be mixed, but it is up 
to the routine to know what type of argument is expected, as it cannot be deter- 
mined at runtime. 

va_end is used to clean up. 

Multiple traversals, each bracketed by va_start ... va_end, are possible. 

EXAMPLE 

This example is a possible implementation of execl( 2). 

#include <varargs.h> 

# define MAXARGS 100 

/ * execl is called by 

execl(file, argl, arg2, ..., (char *)0); 

*/ 

execl(vaalist) 
va del 
{ 

vajist ap; 
char *file; 

char *args[MAXARGS]; 
int argno — 0; 
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va_start(ap); 

file = va_arg(ap, char *); 

while ((args[argno++] = va_arg(ap, char *)) != (char *)0) 

/ 

vaend(ap); 

return execv(file, args); 

SEE ALSO 

exec(2), printf(3S), vprintf(3S). 

NOTES 

It is up to the calling routine to specify how many arguments there are, since it 
is not always possible to determine this from the stack frame. For example, 
execl is passed a zero pointer to signal the end of the list. Printf can tell how 
many arguments are there by the format. 

It is non-portable to specify a second argument of char, short, or float to va_arg, 
since arguments seen by the called function are not char, short, or float. C con- 
verts char and short arguments to int and converts float arguments to double 
before passing them to a function. 
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NAME 

xtproto — multiplexed channels protocol used by xt(7) driver 
DESCRIPTION 

The xt(7) driver contains routines which implement a multiplexed, multi- 
buffered, full-duplex protocol with guaranteed delivery of ordered data via an 
8 -bit byte data stream. This protocol is used for communication between mul- 
tiple UNIX system host processes and an AT&T windowing terminal operating 
under layers( 1). 

The protocol uses packets with a 2-byte header containing a 3-bit sequence 
number, 3-bit channel number, control flag, and data size. The data part of a 
packet may not be larger than 32 bytes. The trailer contains a CRC-16 code in 2 
bytes. Each channel is double-buffered. 

Correctly received packets in sequence are acknowledged with a control packet 
containing an ACK; however, out of sequence packets generate a control packet 
containing a NAK, which will cause the retransmission in sequence of all unack- 
nowledged packets. 

Unacknowledged packets are retransmitted after a timeout interval which is 
dependent on baud rate. Another timeout parameter specifies the interval after 
which incomplete receive packets are discarded. 

FILES 

/usr/include/sys/xtproto.h channel multiplexing protocol definitions 

SEE ALSO 

layers(5). 

layers(l) in the User's Reference Manual. 

xt (7) in the System Administrator's Reference Manual. 
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